doc: classes hyper liées

[privat]

MapRead et Map sont très liées, la première n'est qu'un interface de la seconde restreinte à la lecture seule.

Malheureusement, au niveau du modèle, les classes sont distinctes ce qui fait que dans la documentation de Map la méthode [] n'apparait meme pas.

Une idée pour améliorer les choses?

[Morriar]

Hum... problème intéressant.

Je vois plusieurs solutions au problème. Aucune ne m'a l'air "top" mais ça peut fournir un truc à essayer.

On a déjà parlé de rajouter des "see also" soit manuellement via l'annotation @see à la java soit calculés par l'outil nitdoc directement.

Je n'aime pas trop l'idée de tout déléguer au développeur. Les annotations ne se maintiennent pas aussi bien qu'on pourrait l'espérer. Voyons donc ce qu'on peut faire automatiquement.

1. C'est assez direct et ça va avec la notion d'associer getter et setter: Quand on trouve une méthode foo= on lui associe automatiquement un see also avec foo et vice versa. Je pense que ça marche dans la plupart des cas. Ça fait bien la job pour les attributs et si foo= ne doit pas être lié avec foo alors y'a certainement un problème de sémantique au niveau du nom du service.

2. Fusionner les accesseurs sous le nom de l'attribut. En gros, pour chaque attribut on réunit automatiquement le getter et le setter. Ça ne résout pas le problème de [] mais ça fait la job dans la plupart des cas (en fait pour les trucs avec des attributs).

3. Analyser le contenu de la méthode. Toujours dans l'optique de lier des méthodes qui font des trucs similaires. On peut tout à fait imaginer compter les attributs/méthodes accédés par un méthode. Si deux méthodes appellent toutes les deux à foo on peut se douter qu'elles font un truc semblable. Attention, l'exemple ici est simpliste, il faudrait plutôt y aller à coup de stats et de seuils mais vous voyez l'idée.

4. Ajouter un see also depuis une interface vers les trucs concrets qui l'implémentent (par concret je veux dire une classe nom abstraite).

5. Paire abstraction / implémentation. Celle là peut-être fun, et j'utilise un exemple pour la décrire:

   class Foo
       var foo: Map = new HashMap[Bar, Baz]
       ...
   

   L'idée c'est que le type de foo est une Map mais le type dynamique retourné est une HashMap. Donc quand on type un truc par une Map (abstrait) on utilise une HashMap (concret) pour en fournir une implémentation. On lance quelques mesures pour trouver les types les plus utilisés pour remplacer une Map et hop, une petite liste de see also gratos.

6. Celle là est pas mal biaisée par une idée personnelle mais je la propose quand même. Utiliser des [] ou tout autre opérateur un peu exotique veut dire quelque chose: Le service est tellement évident qu'on peut se permettre d'utiliser un opérateur farfelu pour en présenter la sémantique. Dans le cas de Map ou de Array ce genre de service parait tellent incontournable qu'il devrait apparaître même dans les sous-classes (et même si aucune redéfinition locale existe). Alors pourquoi ne pas tout simplement faire une petite règle spéciale pour toujours afficher les opérateurs farfelus dans toutes les classes (genre une catégorie à part on un bloc dans la side bar)? Je sais pas vous, mais si j'ai le droit de faire un += sur Foo, si je visite Bar (super Foo) ça me tente bien d'apprendre que Bar fourni un += et à quoi il sert? Je veut dire... c'est += et pas foo_bar_baz_truc(a, b, c) quand même!

7. Plus d'idées comme ça mais une bonne revue de littérature sur le sujet s'impose. D'ailleurs si vous avez de bonnes idées proposez!

[privat]

Autre idée: pouvoir indiquer, via une annotation dans la doc de la classe par exemple, que tous les services définis dans telle superclasse doivent etre décrits.