Introduction à la commande javadoc
Chapitre 6: Générer Javadoc
Cette fois, il ne s'agit pas d'un aspect d'implémentation tel que les spécifications Javadoc et la méthode d'écriture, mais Je voudrais me concentrer sur la façon d'utiliser et de faire fonctionner la commande javadoc. Concernant la façon d'écrire des commentaires, quand j'ai appris des livres sur la façon d'écrire Javadoc Je voudrais le résumer.
Présentation de Javadoc
La commande Javadoc analyse les déclarations et les commentaires dans les fichiers source Java et par défaut classe publique, classe protégée, classe imbriquée (hors classe interne anonyme), Documentation d'implémentation pour les interfaces, les constructeurs, les méthodes et les champs Générer au format HTML.
Liste des pages Javadoc
Qu'en est-il de Javadoc, le produit de la commande javadoc, pour faciliter l'explication ultérieure? Voici un exemple de la façon dont la page sera générée.
Page de contenu de base
- ** Page de présentation ** (overview-summary.html) Première page Javadoc. Un aperçu de l'ensemble de l'unité, de l'API et de l'ensemble de packages est rédigé.
- ** Page du package ** (package-summary.html) Une page qui existe pour chaque package. Le contour du paquet est écrit.
- ** Page de classe / page d'interface ** (nom de classe.html) Pages qui existent pour chaque classe et interface. Contient des informations sur les membres et les méthodes appartenant à la classe.
~ Page de présentation ~
~ Page du package ~
~ Page de cours ~
Page de référence mutuelle
- ** Page de hiérarchie de classes ** (overview-tree.html) Il y en a un pour chaque Javadoc. Les éléments auxquels ils appartiennent peuvent être hiérarchisés et répertoriés.
- ** Page de hiérarchie de classes ** (package-tree.html) Il y en a un pour chaque paquet. Les éléments appartenant à un package peuvent être hiérarchisés et répertoriés.
- ** Page de spécification ** (package-use.html) Vous pouvez lister les classes, packages et classes cibles qui utilisent l'interface.
- ** Page API obsolète ** (deprecated-list.html) Vous pouvez lister les classes, méthodes, etc. obsolètes qui pourraient être supprimées à l'avenir.
- ** Page Valeurs de champs constants ** (valeurs-constantes.html) Page pour les valeurs de champ statiques
- ** Page de formulaire sérialisé ** (serialized-form.html) Une page sur les classes qui peuvent être sérialisées (externalisées).
- ** Index ** (index- *. Html) Toutes les classes, interfaces, constructeurs, champs et méthodes, Peut être répertorié par ordre alphabétique.
Page d'assistance
--Page d'aide (help-doc.html) Il contient une barre de navigation et des instructions pour chaque page.
Cadre HTML
La commande javadoc crée quelques cadres HTML. S'il y a un package, un cadre pour la classe sera créé en bas à gauche et un cadre pour les détails sera créé à droite. S'il y a plusieurs packages, un cadre pour le package sera ajouté en haut à gauche.
format de la commande javadoc
#L'ordre dans lequel les arguments de la commande javadoc sont spécifiés est arbitraire.
$ javadoc [options] [packagenames | sourcefilenames] [-subpackages pkg1:pkg2:...]
- options
Options de ligne de commande transmises à la commande javadoc. - packagenames
Le nom du package à traiter. Spécifiez commejava.lang java.awt ''. Vous devez spécifier le package cible individuellement et vous ne pouvez pas utiliser de caractères génériques. Pour le spécifier de manière récursive, utilisez-subpackages '' décrit ci-dessous. - sourcefilenames
Le nom du fichier source à traiter. Chaque fichier commence par un chemin, tel qu'un astérisque (\ *) Vous pouvez inclure des caractères génériques. - -subpackages pkg1:pkg2:...
Récursivement dans le package spécifié et ses sous-packages à partir du fichier source Générez un document. Il n'est pas nécessaire de spécifier le nom du package et le nom du fichier source.
Spécifier le fichier source
Type de fichier source
Les quatre fichiers cibles suivants sont analysés lors de la génération de Javadoc.
- ** Fichier de classe ** Un fichier se terminant par .java. Si le nom de la classe n'est pas valide selon la convention Java, il ne sera pas traité. Exemple) Commencez par un nombre. "-"comprenant. Tel
- ** Fichier de commentaire du package ** Il peut être placé pour chaque package et est placé dans la même hiérarchie que le fichier .java. Décrivez le contour de l'emballage. Le nom du fichier est fixe et il existe les deux spécifications suivantes. --Avant JDK1.5: package.html --JJ1.5 ou version ultérieure: package-info.java
- ** Fichier de commentaires récapitulatifs ** Un fichier pour générer une page de présentation. Le nom et l'emplacement du fichier sont arbitraires, mais généralement Faites-le overview.html et placez-le au niveau supérieur de l'arborescence des sources. Généré en spécifiant le nom du fichier de commentaire récapitulatif avec l'option -overview.
- ** Fichiers dans le répertoire doc-files ** Par exemple, vous souhaitez insérer un fichier image dans Javadoc d'une classe appelée Sample class. Si vous voulez utiliser des fichiers qui s'écartent des règles de .java, appelez doc-files dans la même hiérarchie que .java. En créant et en organisant un répertoire, le fichier stocké peut être analysé.
Comment spécifier divers fichiers source
Il existe trois méthodes principales pour spécifier le fichier source.
** 1. Spécifiez le package ** Étant donné que les caractères génériques ne peuvent pas être utilisés, séparez-les par un espace demi-largeur au format suivant. Spécifiez tous les packages individuellement. La spécification doit être une spécification complète.
java.lang java.lang.reflect java.awt
** 2. Spécifiez le chemin du fichier source **
Spécifiez le chemin du fichier source. Le chemin absolu ou le chemin relatif peut être spécifié,
Pour un chemin relatif, spécifiez le chemin relatif à partir du répertoire actuel.
Des caractères génériques peuvent être utilisés et, si vous en spécifiez plusieurs, séparez-les par un espace demi-largeur.
#### **`/src/java/awt/Sample.java src/java/awt/*Bar.java`**
** 3. Spécifiez les packages de manière récursive avec l'option -subpackages ** Si vous spécifiez un package, vous pouvez spécifier la plage comprenant les sous-packages. Les caractères génériques ne peuvent pas être utilisés. Lorsque vous spécifiez, séparez par deux points (:) au format suivant.
javax.swing
> Normalement, les packages individuels sont rarement spécifiés.
Spécifiez le chemin du fichier source avec un caractère générique ou avec l'option -subpackages
Il est principalement spécifié de manière récursive.
** Ex. Lors de la spécification dans le package **
Lors de la spécification du fichier source dans le package,
Vous ne pouvez pas suivre la hiérarchie du package sans spécifier la racine du package.
Par conséquent, il est nécessaire de spécifier le répertoire qui est le point de départ du package.
Il existe deux façons de spécifier un répertoire:
--Déplacez le répertoire courant vers le répertoire de départ et exécutez la commande javadoc
--Spécifiez le répertoire de départ avec l'option -sourcepath
## options javadoc
Les options pouvant être transmises à la commande javadoc incluent
Il existe deux options: les options de commande javadoc et les options fournies par doclet.
Je n'entrerai pas dans les détails sur les docklets,
Considérez-le comme un modèle qui fournit le format javadoc.
Si vous ne spécifiez pas explicitement un doclet personnalisé, le doclet standard est sélectionné.
### Options majeures
--- vue d'ensemble <chemin \ nom de fichier>
En spécifiant le overview.html placé à un emplacement arbitraire avec le chemin, le overview.html est analysé et
Placez-le sur la page de présentation (overview-summary.html).
Pour le chemin, spécifiez le chemin relatif du répertoire spécifié par -sourcepath.
--- d <chemin>
Sortez le Javadoc généré vers le chemin spécifié.
--- source <version>
Spécifiez la version du code source. Faites correspondre la version à celle de la compilation.
--1.5: Accepte le code introduit dans JDK 1.5. Valeur par défaut.
--1.4: Accepte le code comprenant les assertions introduites dans JDK 1.4.
--1.3: Ne prend pas en charge les assertions, les génériques et les autres fonctionnalités de langage introduites dans JDK 1.3 et versions ultérieures.
--- classpath <liste des chemins>
Spécifiez le chemin pour rechercher la classe de référence (.class).
Les classes de référence incluent toutes les classes documentées et toutes référencées par ces classes.
Comprend la classe. La plage de recherche est le sous-répertoire sous le chemin spécifié.
Si le chemin d'accès aux classes n'est pas défini, le répertoire courant sera le chemin d'accès aux classes.
--- sourcepath <liste des chemins>
Spécifiez le chemin de classe du fichier source. (Si vous passez des packages ou des sous-packages)
La plage de recherche est le sous-répertoire sous le chemin spécifié. Avec cette option,
Si -sourcepath est omis, ** la même valeur que le chemin de classe ** sera définie.
Si -classpath est également omis, ** répertoire courant ** est défini.
--- J <options de commande java>
Transmettez les options au système d'exécution java qui exécute javadoc. (-J-Xmx32m etc.)
### Options spécifiées à documenter
--- sous-colis <Colis 1: Colis 2 ...>
La plage de génération peut être le package spécifié et ses sous-packages et inférieurs. (Plusieurs packages peuvent être spécifiés)
-sourcepath est requis lors de l'utilisation de -subpackages.
--- bootclasspath <liste des chemins>
Spécifiez le chemin où réside la classe de démarrage.
### Options du système de contrôle à documenter
- -public
Afficher uniquement les classes publiques et les membres.
- -protected
Afficher uniquement les classes et les membres protégés et publics. Paramètres par défaut.
- -package
Afficher uniquement les classes et les membres du package, protégés et publics.
- -private
Afficher toutes les classes et tous les membres.
--- exclure <Paquet 1: Paquet 2 ...>
Exclut le package spécifié et ses sous-packages de la liste spécifiée par -subpackages.
### Options du Docklet
--- doclet <classe>
Spécifiez un docklet autre que le docklet standard. Spécifiez la classe de démarrage avec les spécifications complètes.
Le format pour spécifier la classe de démarrage est `` `` -doclet com.example.doclets.SampleDoclet```.
Le chemin d'accès à la classe de démarrage est défini par l'option -docletpath.
--- docletpath <chemin de classe 1: chemin de classe 2 ...>
Le fichier de classe de début de doclet spécifié par l'option -doclet et le fichier jar dépendant
Spécifiez le chemin vers. Le chemin du fichier jar si le fichier de classe de démarrage se trouve dans le fichier jar
Seul peut être spécifié. Vous pouvez spécifier un chemin absolu ou un chemin relatif à partir du répertoire actuel.
Cette option n'est pas nécessaire si la classe de début de doclet souhaitée se trouve dans le chemin de recherche.
```shell
#SampleDocklet/src/com/example/Supposons que ce soit directement sous les doclets
-doclet com.example.doclets.SampleDoclet -docletpath /src:/lib/doclet.jar
Options de débogage
- -verbose
Afficher des messages détaillés lors de l'exécution de javadoc. Si non spécifié, lors du chargement du fichier source et lors de la génération du document (par fichier source), Et un message est affiché au moment du tri (une seule fois en une seule exécution). Si spécifié, des informations détaillées telles que le temps (en millisecondes) requis pour analyser chaque fichier source Java Un message s'affiche. - -quiet
Supprimez les messages autres que les messages d'erreur et les messages d'avertissement.
Options d'internationalisation
--- locale
Courir
Ici, des commentaires et des fichiers pour la génération Javadoc sont ajoutés à l'exemple de code utilisé jusqu'à présent.
La configuration suivante ajoutée est utilisée comme exemple de code.
UseCommons.java
package com.example.app;
import org.apache.commons.lang3.StringUtils;
import com.example.util.StrFactory;
/**
*Une classe pour utiliser Apache Commons.
*/
public class UseCommons {
public static void main(String[] args) {
System.out.println(CommonsHelper.returnNgStrIfHasProbrem(null));
System.out.println(CommonsHelper.returnNgStrIfHasProbrem(""));
StrFactory strFactory = new StrFactory();
System.out.println(CommonsHelper.returnNgStrIfHasProbrem(strFactory.sayHelloWorld()));
}
static class CommonsHelper {
static String returnNgStrIfHasProbrem (String target) {
if (StringUtils.isEmpty(target)) {
return "NG";
} else if (StringUtils.isBlank(target)) {
return "NG";
}
return target;
}
}
}
StrFactory.java
package com.example.util;
/**
*Une classe d'usine pour générer différentes chaînes de caractères.
*/
public class StrFactory {
/**
* "Hello World!"Sera retourné.
*/
public String sayHelloWorld() {
return "Hello World!";
}
}
package.html
<html>
<body>
Ceci est un exemple de commentaire de package.
</body>
</html>
overview.html
<html>
<body>
Ceci est un commentaire récapitulatif de l'exemple.
</body>
</html>
Comme mentionné ci-dessus, après avoir préparé le fichier source, exécutez la commande suivante.
#Le répertoire actuel est/java-C'est un échantillon.
$ javadoc -classpath ./src:./lib/commons-lang3-3.10.jar -subpackages com.example -overview ./overview.html -d ./docs
Une fois exécuté, Javadoc sera généré dans / java-sample / docs spécifié comme destination de sortie.
Pour voir la Javadoc, ouvrez index.html.
Voici la sortie réelle.
en conclusion
L'exemple de code n'inclut pas les commentaires minimum requis, En fait, utilisez HTML pour les commentaires, insérez des images, reportez-vous à des bibliothèques externes, etc. Vous pouvez faire diverses choses, alors lisez ou recherchez des livres spécialisés sur leur mise en œuvre. J'espère que vous étudierez.
Recommended Posts