Comment puis-je faire le travail d'héritage javadoc pour les API externes? (Avec Maven2)

Question

Lorsqu'une classe l'emporte sur une méthode concrète ou met en œuvre et méthode abstraite, la Javadoc est héritée automatiquement à moins explicitement remplacé.

Ou, au moins l'outil essaie de le faire. Il semble qu'il ne fonctionne pas pour les API externes dont le lien. Par exemple, quand je dans mon code java.util.Map mettre en œuvre, ou quelque chose d'autre de la JRE, les javadocs ne sont pas hérités / copiés à partir des Javadocs / apidocs JRE.

Dans mon cas particulier, je suis en train de configurer ce plug-in dans le Maven2 Javadoc, mais il est le même quand je lance l'outil CLI javadoc directement.

Ma configuration du plugin Maven2 Javadoc ressemble actuellement à ceci:

<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.7</version>
      <configuration>
        <stylesheet>maven</stylesheet>
        <links>
          <link>http://download.oracle.com/javase/6/docs/api</link>
        </links>
      </configuration>
    </plugin>
  </plugins>
</reporting>

Les pointeurs sur la façon de faire ce travail?

Answer 1

@Stephen mentionné, le fichier source pour la méthode héritée doit être disponible et doit être sur le chemin d'accès spécifié par -sourcepath. Ceci est expliqué dans la documentation javadoc:

  

Copie automatique des commentaires Méthode

     

L'outil Javadoc a la capacité de   copie ou méthode « Hériter » dans les commentaires   dans les classes et interfaces du   après deux circonstances.   Constructors, champs et imbriqués   les classes ne héritent pas de commentaires doc.

     

  

• héritent automatiquement de commentaire à remplir le texte manquant - Lorsqu'un principale   Description , ou @return,   @param ou tag @throws est manquant   d'un commentaire de la méthode, la Javadoc   copies outil affiche les principaux correspondants   description ou commentaire de la balise   elle remplace la méthode ou des outils (si   quelconque), selon l'algorithme   ci-dessous.

       

  Plus précisément, quand une étiquette de @param pour un particulier   paramètre est manquant, alors le commentaire   pour ce paramètre est copié à partir du   procédé comprenant en outre l'héritage   hiérarchie. Quand une étiquette de @throws pour une   exception particulière est manquante, le   tag @throws est copié que si cette   exception est déclarée.

       

  Ce comportement contraste avec la version 1.3 et antérieures, où le   présence de toute description principale ou   tag empêcherait tous les commentaires de   étant héritée.

  

• Explicitement hériter commentaire avec tag {@inheritDoc} - Insérer la   tag en ligne {@inheritDoc} dans un   Description de la méthode principale ou @return,   @param ou tag @throws commentaire -   le principal correspondant hérité   description ou commentaire tag est copié   dans cet endroit.

  

     

Le fichier source pour le hérité   méthode doit seulement être sur le chemin   spécifié par -sourcepath   le commentaire de doc pour être réellement   disponible pour copier. Ni la classe   ni son emballage doit être passé dans   sur la ligne de commande. cela contraste   avec 1.3.x et les versions antérieures, où   la classe devait être un rel="noreferrer"> classe

Il faudrait donc utiliser le <sourcepath> paramètre de configuration optionnelle du plugin javadoc (qui contient par défaut les sources du projet).

---

Par ailleurs, <links/> sont quelque chose d'autre, <links/> sont utilisés pour ajouter des liens de références croisées à des projets externes. Et en fait, ils ne devraient pas être utilisés pour le JDK. De liens Configuration :

  

Depuis 2.6, un lien API Javadoc, selon la version utilisée par votre JDK projet, seront ajoutés. La version de l'API Javadoc est détectée à partir de la valeur de la le paramètre de <source/> dans le org.apache.maven.plugins:maven-compiler-plugin (défini dans ${project.build.plugins} ou en ${project.build.pluginManagement}) ou Computed via l'exécutable outil Javadoc. Si vous voulez sauter ce lien, vous devez configurer <detectJavaApiLink/> pour false.

     

Remarque: si vous utilisez un JDK non pris en charge comme 7.0, vous pouvez ajouter l'URL API Javadoc en utilisant le paramètre de <javaApiLinks/>, à savoir:

<configuration>
  <javaApiLinks>
    <property>
      <name>api_1.7</name>
      <value>http://download.java.net/jdk7/docs/api/</value>
    </property>
  </javaApiLinks>
  ...
</configuration>

     

Reportez-vous au paramètre <links/> pour plus d'informations.

En supposant que vous avez configuré un 1.6 niveau source dans le plug-in du compilateur, des liens de références croisées à l'API Java fonctionne exactement (liens pointent vers http://download.oracle.com/javase/6/docs/api/ ), il n'y a rien à ajouter pour l'API Java.

---

  

Ni fonctionne hors de la boîte pour moi. Je devais ajouter la section des liens pour faire le travail de références croisées.

Bizarre

. Avez-vous spécifié en fait le niveau de source complier comme documenté? Juste au cas où, voici ce qui fonctionne pour moi:

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
      <source>1.6</source>
      <target>1.6</target>
    </configuration>
  </plugin>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.7</version>
    <configuration>
      <!-- No need for this -->
      <!--
      <javaApiLinks>
        <property>
          <name>api_1.6</name>
          <value>http://download.oracle.com/javase/6/docs/api/</value>
        </property>
      </javaApiLinks>
      -->
      <links>
        <link>http://commons.apache.org/dbcp/apidocs/</link>
        <link>http://commons.apache.org/fileupload/apidocs/</link>
      </links>
    </configuration>
  </plugin>

Answer 2

Je ne peux pas vous donner une réponse définitive, mais je pense que la pièce manquante dans le puzzle est que l'utilitaire javadoc doit être en mesure de trouver le code source des API externes pertinentes pour l'héritage javadoc au travail.

Answer 3

J'avais une question similaire sur StackOverflow qui m'a aidé à résoudre ce problème mieux que la réponse acceptée de cette questsion: maven-plugin-javadoc et inheritDoc pour les classes Java de base API

Résumé: Afin d'hériter de la Javadoc des classes Java de base, vous devez décompressez leurs sources et de les inclure dans la construction Javadoc. Les sources des classes de base Java sont fournis sont dans un fichier src.zip dans le distro JDK.