Java Language => Documentation du code Java

Introduction

La documentation du code Java est souvent générée à l'aide de javadoc . Javadoc a été créé par Sun Microsystems dans le but de générer une documentation API au format HTML à partir du code source Java. L'utilisation du format HTML permet de créer des liens hypertexte entre des documents associés.

Syntaxe

/ ** - début de JavaDoc sur une classe, un champ, une méthode ou un package
@author // Pour nommer l'auteur de la classe, de l'interface ou de l'énumération. C'est requis.
@version // La version de cette classe, interface ou enum. C'est requis. Vous pouvez utiliser des macros telles que% I% ou% G% pour votre logiciel de contrôle de code source pour remplir la vérification.
@param // Affiche les arguments (paramètres) d'une méthode ou d'un constructeur. Spécifiez une balise @param pour chaque paramètre.
@return // Affiche les types de retour pour les méthodes non vides.
@exception // Indique quelles exceptions peuvent être émises par la méthode ou le constructeur. Les exceptions qui DOIVENT être prises doivent être listées ici. Si vous le souhaitez, vous pouvez également inclure ceux qui n'ont pas besoin d'être interceptés, comme ArrayIndexOutOfBoundsException. Spécifiez une exception @ pour chaque exception pouvant être levée.
@throws // Identique à @exception.
@see // Liens vers une méthode, un champ, une classe ou un package. Utiliser sous la forme de package.Class # quelque chose.
@since // Lorsque cette méthode, champ ou classe a été ajouté. Par exemple, JDK-8 pour une classe comme java.util.Optional <T> .
@serial, @serialField, @serialData // Utilisé pour afficher le serialVersionUID.
@deprecated // Pour marquer une classe, une méthode ou un champ comme étant obsolète. Par exemple, un serait java.io.StringBufferInputStream . Voir une liste complète des classes obsolètes existantes ici .
{@link} // Similaire à @see, mais peut être utilisé avec du texte personnalisé: {@link #setDefaultCloseOperation (int closeOperation) voir JFrame # setDefaultCloseOperation pour plus d'informations}.
{@linkplain} // Similaire à {@link}, mais sans la police de code.
{@code} // Pour le code littéral, tel que les balises HTML. Par exemple: {@code <html> </ html>}. Cependant, cela utilisera une police à espacement fixe. Pour obtenir le même résultat sans la police monospace, utilisez {@literal}.
{@literal} // Identique à {@code}, mais sans la police monospace.
{@value} // Affiche la valeur d'un champ statique: la valeur de JFrame # EXIT_ON_CLOSE est {@value}. Vous pouvez également créer un lien vers un champ donné: Utilise le nom de l'application {@value AppConstants # APP_NAME}.
{@docRoot} // Le dossier racine du HTML JavaDoc relatif au fichier en cours. Exemple: <a href="{@docRoot}/credits.html"> Crédits </a>.
HTML est autorisé: <code> "Salut les cookies" .substring (3) </ code>.
* / - fin de la déclaration JavaDoc

Remarques

Javadoc est un outil fourni avec le JDK qui permet de convertir les commentaires dans le code en une documentation HTML. La spécification de l'API Java a été générée à l'aide de Javadoc. La même chose est vraie pour une grande partie de la documentation des bibliothèques tierces.

Documentation de classe

Tous les commentaires Javadoc commencent par un commentaire de bloc suivi d'un astérisque ( /** ) et se terminent lorsque le commentaire de bloc fait ( */ ). Facultativement, chaque ligne peut commencer par des espaces blancs arbitraires et un seul astérisque; ceux-ci sont ignorés lorsque les fichiers de documentation sont générés.

/**
 * Brief summary of this class, ending with a period.
 *
 * It is common to leave a blank line between the summary and further details.
 * The summary (everything before the first period) is used in the class or package 
 * overview section.
 *
 * The following inline tags can be used (not an exhaustive list): 
 * {@link some.other.class.Documentation} for linking to other docs or symbols
 * {@link some.other.class.Documentation Some Display Name} the link's appearance can be 
 * customized by adding a display name after the doc or symbol locator
 * {@code code goes here} for formatting as code
 * {@literal <>[]()foo} for interpreting literal text without converting to HTML markup 
 * or other tags.
 *
 * Optionally, the following tags may be used at the end of class documentation 
 * (not an exhaustive list):
 *
 * @author John Doe
 * @version 1.0
 * @since 5/10/15
 * @see some.other.class.Documentation
 * @deprecated This class has been replaced by some.other.package.BetterFileReader
 * 
 * You can also have custom tags for displaying additional information.
 * Using the @custom.<NAME> tag and the -tag custom.<NAME>:htmltag:"context"
 * command line option, you can create a custom tag.
 *
 * Example custom tag and generation:
 * @custom.updated 2.0    
 * Javadoc flag: -tag custom.updated:a:"Updated in version:"
 * The above flag will display the value of @custom.updated under "Updated in version:"
 *
 */
public class FileReader {
}

Les mêmes balises et formats utilisés pour les Classes peuvent également être utilisés pour les Enums et les Interfaces .

Méthode Documentation

/**
 * Brief summary of method, ending with a period.
 *
 * Further description of method and what it does, including as much detail as is 
 * appropriate.  Inline tags such as
 * {@code code here}, {@link some.other.Docs}, and {@literal text here} can be used.
 *
 * If a method overrides a superclass method, {@inheritDoc} can be used to copy the 
 * documentation
 * from the superclass method
 *
 * @param stream Describe this parameter.  Include as much detail as is appropriate
 *               Parameter docs are commonly aligned as here, but this is optional.
 *               As with other docs, the documentation before the first period is 
 *               used as a summary.
 *
 * @return Describe the return values.  Include as much detail as is appropriate
 *         Return type docs are commonly aligned as here, but this is optional.
 *         As with other docs, the documentation before the first period is used as a 
 *         summary.
 *
 * @throws IOException Describe when and why this exception can be thrown.
 *                     Exception docs are commonly aligned as here, but this is 
 *                     optional.
 *                     As with other docs, the documentation before the first period 
 *                     is used as a summary.
 *                     Instead of @throws, @exception can also be used.
 *
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated  Describe why this method is outdated. A replacement can also be specified.
 */
public String[] read(InputStream stream) throws IOException {
    return null;
}

Documentation de terrain

/**
 * Fields can be documented as well.
 * 
 * As with other javadocs, the documentation before the first period is used as a
 * summary, and is usually separated from the rest of the documentation by a blank 
 * line.
 * 
 * Documentation for fields can use inline tags, such as:
 * {@code code here}
 * {@literal text here}
 * {@link other.docs.Here}
 * 
 * Field documentation can also make use of the following tags:
 * 
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated Describe why this field is outdated
 */
public static final String CONSTANT_STRING = "foo";

Documentation du package

Java SE 5

Il est possible de créer une documentation au niveau du package dans Javadocs à l'aide d'un fichier appelé package-info.java . Ce fichier doit être formaté comme ci-dessous. Les espaces blancs et les astérisques sont facultatifs, généralement présents dans chaque ligne pour la raison du formatage

/**
 * Package documentation goes here; any documentation before the first period will 
 * be used as a summary.
 *
 * It is common practice to leave a blank line between the summary and the rest
 * of the documentation; use this space to describe the package in as much detail
 * as is appropriate.
 * 
 * Inline tags such as {@code code here}, {@link reference.to.other.Documentation},
 * and {@literal text here} can be used in this documentation.
 */
package com.example.foo;

// The rest of the file must be empty.

Dans le cas ci-dessus, vous devez placer ce fichier package-info.java dans le dossier du package Java com.example.foo .

Liens

La liaison à d'autres Javadocs se fait avec la balise @link :

/**
 * You can link to the javadoc of an already imported class using {@link ClassName}.
 *
 * You can also use the fully-qualified name, if the class is not already imported: 
 *  {@link some.other.ClassName}
 *
 * You can link to members (fields or methods) of a class like so:
 *  {@link ClassName#someMethod()}
 *  {@link ClassName#someMethodWithParameters(int, String)}
 *  {@link ClassName#someField}
 *  {@link #someMethodInThisClass()} - used to link to members in the current class
 *  
 * You can add a label to a linked javadoc like so:
 *  {@link ClassName#someMethod() link text} 
 */

Avec le tag @see vous pouvez ajouter des éléments à la section Voir aussi . Comme @param ou @return l'endroit où ils apparaissent n'est pas pertinent. La spécification dit que vous devriez l'écrire après @return .

/**
 * This method has a nice explanation but you might found further
 * information at the bottom.
 *
 * @see ClassName#someMethod()
 */

Si vous souhaitez ajouter des liens vers des ressources externes, vous pouvez simplement utiliser la balise HTML <a> . Vous pouvez l'utiliser en ligne n'importe où ou à l'intérieur des balises @link et @see .

/**
 * Wondering how this works? You might want
 * to check this <a href="http://stackoverflow.com/">great service</a>.
 *
 * @see <a href="http://stackoverflow.com/">Stack Overflow</a>
 */

Construction de Javadocs à partir de la ligne de commande

De nombreux IDE prennent en charge la génération automatique de HTML à partir de Javadocs; certains outils de construction ( Maven et Gradle , par exemple) ont également des plugins capables de gérer la création HTML.

Cependant, ces outils ne sont pas requis pour générer le HTML Javadoc; Cela peut être fait en utilisant l'outil de ligne de commande javadoc .

L'utilisation la plus élémentaire de l'outil est la suivante:

javadoc JavaFile.java

Qui générera du HTML à partir des commentaires Javadoc dans JavaFile.java .

Une utilisation plus pratique de l'outil en ligne de commande, qui lit tous les fichiers Java dans [source-directory] manière récursive, crée la documentation pour [package.name] et tous les sous-packages, et place le code HTML généré dans le [docs-directory] est:

javadoc -d [docs-directory] -subpackages -sourcepath [source-directory] [package.name]

Documentation du code en ligne

Outre la documentation Javadoc, le code peut être documenté en ligne.

Les commentaires sur une seule ligne sont lancés par // et peuvent être positionnés après une instruction sur la même ligne, mais pas avant.

public void method() {
  
  //single line comment
  someMethodCall(); //single line comment after statement
  
}

Les commentaires multi-lignes sont définis entre /* et */ . Ils peuvent couvrir plusieurs lignes et peuvent même être positionnés entre les instructions.

public void method(Object object) {
  
  /*
    multi 
    line 
    comment
  */
  object/*inner-line-comment*/.method(); 
}

JavaDocs est une forme spéciale de commentaires sur plusieurs lignes, commençant par /** .

Comme un trop grand nombre de commentaires en ligne peut nuire à la lisibilité du code, ils doivent être utilisés de manière limitée au cas où le code ne serait pas suffisamment explicite ou que la décision de conception n'est pas évidente.

Un autre cas d'utilisation des commentaires sur une seule ligne est l'utilisation de TAG, qui sont des mots-clés courts, basés sur des conventions. Certains environnements de développement reconnaissent certaines conventions pour de tels commentaires uniques. Des exemples communs sont

//TODO
//FIXME

Ou émettre des références, par exemple pour Jira

//PRJ-1234

Extraits de code dans la documentation

La manière canonique d'écrire du code dans la documentation est la construction {@code } . Si vous avez du code multiligne, retournez-le dans <pre></pre> .

/**
 * The Class TestUtils.
 * <p>
 * This is an {@code inline("code example")}.
 * <p>
 * You should wrap it in pre tags when writing multiline code.
 * <pre>{@code
 *  Example example1 = new FirstLineExample();
 *  example1.butYouCanHaveMoreThanOneLine();
 * }</pre>
 * <p>
 * Thanks for reading.
 */
class TestUtils {

Parfois, vous devrez peut-être mettre du code complexe dans le commentaire javadoc. Le signe @ est particulièrement problématique. L'utilisation de l'ancienne <code> côté de la construction {@literal } résout le problème.

/**
 * Usage:
 * <pre><code>
 * class SomethingTest {
 * {@literal @}Rule
 *  public SingleTestRule singleTestRule = new SingleTestRule("test1");
 *
 * {@literal @}Test
 *  public void test1() {
 *      // only this test will be executed
 *  }
 *
 *  ...
 * }
 * </code></pre>
 */
class SingleTestRule implements TestRule { }

Modified text is an extract of the original Stack Overflow Documentation

Sous licence CC BY-SA 3.0

Non affilié à Stack Overflow

Java Language
Documentation du code Java

Recherche…