JavaDoc: où append des notes / remarques à la documentation?

Lors du codage en C #, j’ai toujours trouvé les remarks les balises très utiles pour fournir des notes sur l’implémentation d’une classe ou d’une méthode, ou pour donner des informations sur la théorie de ce que j’implémentais. J’utilise maintenant Java mais je ne trouve pas de balise JavaDoc appropriée pour cela. Peut-être qu’en Java, vous accomplissez cela différemment, est-ce que quelqu’un le sait?

Autant que je sache, il n’y a pas de tag Javadoc dédié pour les notes ou les remarques. Généralement, la première phrase de Javadoc devrait donner une brève description de la classe / méthode / champ. Ensuite, la description complète devrait suivre. Et si vous voulez inclure des notes, un paragraphe spécialisé avec une “Note:” précédé devrait suffire.

 /** * Brief description. Full description of the method, generally without * implementation details. * 

* Note: Additional information, eg your implementation notes or remarks. *

* @param input description of the parameter * @return description of return value * * @since version * @author name of the author */ public boolean doSomething(Ssortingng input) { // your code }

Avec l’itération 8 du langage de programmation Java, les développeurs ont finalement reçu trois balises supplémentaires qu’ils peuvent utiliser dans la documentation de leur code – et qui devraient répondre à vos besoins: @apiNote , @implSpec et @implNote (cf., par exemple, pour une discussion plus détaillée: blog.codefx.org/java/new-javadoc-tags/ ).

Si vous pensez que les détails de l’implémentation sont suffisamment intéressants pour faire partie du Javadoc, vous devez simplement les fournir dans un paragraphe du commentaire Javadoc lui-même:

 /** * Does something. * 

* Implementation details:
* Blah blah blah... *

*/ public void doSomething() { // ... }

Vous pouvez également créer vos propres balises personnalisées.

Voici un commentaire javadoc qui inclut la balise personnalisée “@note”:

  /** * Quark represents a quark. * * @note If you spin a quark, it will spin forever! */ public class Quark { } 

Pour générer des javadocs pour ce qui précède, lancez javadoc comme ceci:

javadoc -tag note: a: “Note:” Quark.java

Source: http://www.developer.com/java/other/article.php/3085991/Javadoc-Programming.htm