Discussion :

[joseph_p]

Salut !

Je lisais l'autre jour un article de the register sur le thème suivant : quelle est la grande différence entre la doc API de Microsoft et de php ?

Non seulement une lenteur bien plus grande pour Microsoft mais aussi et surtout la possibilité de saisir des commentaires sous l'API php. L'auteur continuait sur le fait que ces commentaires étaient bien souvent très instructifs et en plus servaient ensuite à affiner les descriptions intégrées à l'API, pour le plus grand bénéfice de tous.

Pour la petite histoire, l'article disait que Microsoft avait décidé d'ouvrir un wiki sur le thème, mais que cela ne comblait pas vraiment le manque de commentaires dans leurs APIs.

Pour ma part, à la réflexion, je trouve vraiment que l'apport de commentaires directement sous les API serait bienvenu.

Qu'en pensez vous ?

Pour sûr, il faudrait amender un peu la génération de la Javadoc (avec une option pour avoir les commentaires activés et des modalités derrière de mise en place sur un serveur web Java avec ou sans db), mais au final le jeu en vaudrait la chandelle je trouve...

++
ZedroS

[nicgando]

Pour moi la Javadoc est une documentation hiérarchisée via les liens hypertextes
Donc si une API a besoin de plus de commentaires pour sa compréhension il faut étoffer la Javadoc.

Par contre ce qui serait pas mal c'est la génération de diagramme de classe simple; un peu comme Doxygen
Ou bien la possibilité d'ajouter des jpeg pour mettre des shémas d'architecture

[joseph_p]

Pour moi la Javadoc est une documentation hiérarchisée via les liens hypertextes
Donc si une API a besoin de plus de commentaires pour sa compréhension il faut étoffer la Javadoc.

Je trouve que donner la possibilité de déposer des commentaires est de loin la meilleure façon de procéder pour signaler ce type de besoin non ?

Par contre ce qui serait pas mal c'est la génération de diagramme de classe simple; un peu comme Doxygen
Ou bien la possibilité d'ajouter des jpeg pour mettre des shémas d'architecture

C'est vrai que ça pourrait aussi aider. Mais là encore ça resterait uniquement selon la perception de l'auteur, alors que des commentaires pourraient lui signaler le besoin de faire une mise à jour

[gronono]

Bonjour,

La javadoc s'écrit avec de l'HTML. Tu peux donc ajouter des images via la balise <img src="...." />. Il faut par contre penser à ajouter les images lorsque tu livres la javadoc.

Sinon je n'ai pas compris la notion de commentaire. C'est les utilisateurs qui mettent les commentaires ? Ils sont stockés où, dans le code ou séparement ? Y a t'il une séparation du sources et de la documention ?

La javadoc n'exclus des guides d'utilisation comme un "Quick Start", "How-to" ou des bonnes pratiques. Je trouve que c'est très ennuyant de parcourir des centaines de pages de javadoc pour trouver la méthode (ou la classe) idéale qui fait toute seule.

[joseph_p]

Je pense que nicgando parlait plus de diagrammes de classes UML générés à la volée.

Pour ce qui est des commentaires, ce serait à la sauce php, cad en bas de chaque page de la Javadoc. Cela a beaucoup aidé php : API pas claire ? Paf, des exemples en bas de page pour bien détailler et puis, plus tard, c'est intégré à l'API elle même.

Cela donne une vraiment une valeur ajoutée à ce genre de pages, parce que là, actuellement, si l'API présentée ne parle pas au développeur il faut qu'il cherche ailleurs sur le net, ce qui induit une dispersion dommageable d'information.