web-dev-qa-db-fra.com

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 sait ?

javacoding-stylejavadoc
43
tunnuz

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. Ensuite, la description complète devrait suivre. Et si vous souhaitez inclure des notes, un paragraphe spécialisé avec un "Note:" ajouté 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
}
43
janhink

Avec l'itération 8 du langage de programmation Java Java, les développeurs ont enfin 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/ ).

21
fbahr

Si vous pensez que les détails d'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.
 * <p>
 * <b>Implementation details:</b><br />
 * Blah blah blah...
 * </p>
 */
public void doSomething() {
    // ...
}
5
Laurent Pireyn

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: "Remarque:" Quark.Java

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

5
Naveen