Je mène mes recherches de Doctorat sur la facilité d'utilisation de la documentation Javadoc et mes conclusions en fait aller à l'encontre de la "instructions officielles" fournie par le Soleil (tout document et le document), et de fournir un soutien pour la "agile" approche (écrire ce qui est utile).
En un mot, le problème, c'est que lorsque vous écrivez tout, vous êtes essentiellement la rédaction d'un cahier des charges - des détails qui vont permettre à quelqu'un qui "se soucie vraiment" apprendre tout au sujet de votre fonction et éventuellement écrire un plan de test complet. Ce qui est important dans de nombreuses applications.
CEPENDANT, dans la vie quotidienne des scénarios de développement, peu de développeurs vont passer leur temps à lire tout ce que vous avez fournis, (je peux vous montrer les numéros). Ils vont écrémé, et ils vont manquer d'informations.
Souvent, les choses les plus importantes à communiquer directives sont généralement faites et ne faites pas les instructions ou des avertissements et des autres "surprenant" de l'information. Seules certaines méthodes de transmettre ces, et ils sont souvent perdus entre le cahier des charges.
Par l'écriture d'élaborer la documentation Javadoc vous sont effectivement cacher les directives importantes et de réduire les chances qu'ils seraient consommés. Les utilisateurs ont également tendance à éviter de lire la documentation Javadoc qui ont l'air trop longtemps.
Mon approche de ce problème est du à l'explicite étiquetage des directives, de sorte qu'un utilisateur l'écrémage de la documentation Javadoc pourrait les voir. J'ai une liste de tags sur mon site.
J'ai également développé un outil appelé eMoose qui met en lumière les appels qui ont directives, et nous avons eu de bons résultats de laboratoire avec elle, et nous allons le présenter à EclipseCon cette année. Contactez-moi si vous souhaitez plus de chiffres que j'ai.
Comme pour ce que vous avez spécifiquement demandé à ce sujet: Si vous y allez avec de documenter tout, allez basées sur le Soleil le specs, mais que signifie documenter les même choses évidentes. Essayez d'éviter l'ajout de code HTML, car elle nuit à la lisibilité, sans l'aide d'un IDE. Le livre "Code Propre" a une grande section sur la documentation.
Voici les balises personnalisées que nous avons jugé nécessaire par l'arpentage de nombreuses Api:
d'utilisation.restriction - Interdit l'utilisation de la méthode à partir de certains contextes (par exemple, "ne pas appeler depuis le thread d'INTERFACE utilisateur") ou qui définit les entités autorisées à faire l'invocation (par exemple, "être appelée uniquement à partir de débogage de l'infrastructure")
d'utilisation.le protocole en voiture de l'invocation de la séquence. Par exemple "ne pas appeler avant de vous invoquée X" ou "n'oubliez pas d'aviser Y après l'appel de cette".
d'utilisation.filetage - Transmet certaines questions relatives à l'enfilage, par exemple en exigeant l'utilisation d'un système de thread ou en indiquant que l'exécution peut bloquer.
d'utilisation.verrouillage de Véhicule spécifique de verrouillage exigences
d'utilisation.la performance Transmet au client qu'il y a quelque problème de performance avec l'aide de cette méthode. Par exemple, qu'il prend beaucoup de temps
d'utilisation.paramètre - Transmet des instructions spécifiques sur la valeur de retour, telles que la libération de responsabilités. Ne pas l'utiliser pour des choses insignifiantes (utiliser le @param tag pour ceux).
d'utilisation.de retour Transmet des instructions spécifiques sur la valeur de retour, telles que la libération de responsabilités. Ne pas l'utiliser pour des choses insignifiantes (utiliser le @return balise pour ceux).
d'utilisation.sideeffect - Alertes à l'utilisateur de certains sideeffect associés avec l'invocation de cette méthode
d'utilisation.la sécurité alerte l'utilisateur pour certaines implications en matière de sécurité ou les conditions associées à l'invocation de cette méthode.
d'utilisation.alternative - Transmet aux utilisateurs qu'ils peuvent vouloir utiliser une méthode différente. Par exemple, "à cause d'un rafraîchissement, d'appel de X à la place".
d'utilisation.recommandation - confère à l'utilisateur qu'il peut vouloir effectuer des opérations supplémentaires. Par exemple, "vous pouvez valider l'URL d'abord".
d'utilisation.la limitation des Alertes à l'utilisateur de certains (inattendue) limitation dans le fonctionnement de la méthode. Par exemple, "ne pas annoncer des changements aux auditeurs"
d'utilisation.patternrole - donne à l'utilisateur que la méthode ou de la classe est partie d'un modèle. Rarement utilisé.
d'utilisation.association Transmet à l'utilisateur que la méthode ou de la classe est associée à une autre entité. Rarement utilisé.
Ci-dessous je suis coller une photo de ce que l'outil ressemble à l'usage: il y a deux tagged choses dans la JavaDoc de la méthode, et l'un des appels est mis en surbrillance pour indiquer que la cible a une directive.
![alt text]()
