JavaDoc: où ajouter des notes / Remarques à la documentation?
Lors du codage en C#, j'ai toujours trouvé la balise remarks très utile 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 d'une manière différente, est-ce que quelqu'un le sait?
4 réponses
Pour autant que je sache, il n'y a pas de balise Javadoc dédiée 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. Puis la description complète devrait suivre. Et si vous voulez inclure des notes, un paragraphe spécialisé avec un" Note: "préfixé devrait suffire.
/**
* Brief description. Full description of the method, generally without
* implementation details.
* <p>
* Note: Additional information, e.g. your implementation notes or remarks.
* </p>
* @param input description of the parameter
* @return description of return value
*
* @since version
* @author name of the author
*/
public boolean doSomething(String 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 d'implémentation sont assez intéressants pour faire partie du Javadoc, vous devriez simplement les fournir dans un paragraphe dans le commentaire Javadoc lui-même:
/**
* Does something.
* <p>
* <b>Implementation details:</b><br />
* Blah blah blah...
* </p>
*/
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, exécutez javadoc comme ceci:
Javadoc-tag note: A:" Note: "Quark.java
Source: http://www.developer.com/java/other/article.php/3085991/Javadoc-Programming.htm