Wie kann ich javadoc Vererbung Arbeit für externen APIs machen? (Mit Maven2)

StackOverflow https://stackoverflow.com/questions/3401642

Frage

Wenn eine Klasse ein konkretes Verfahren oder Geräte und abstrakte Methode überschreibt, wird das Javadoc automatisch vererbt, sofern nicht ausdrücklich überschrieben.

Oder zumindest versucht, das Werkzeug, dies zu tun. Es scheint, es nicht für die verlinkten externe APIs funktioniert. Zum Beispiel, wenn ich in meinem Code java.util.Map implementieren, oder etwas anderes aus der JRE, werden die javadocs nicht vererbt / von der JRE javadocs / apidocs kopiert.

In meinem speziellen Fall, ich versuche, dies in der Maven2 Javadoc Plugin zu konfigurieren, aber es ist das gleiche, wenn ich das javadoc CLI-Tool direkt ausgeführt werden.

Meine Maven2 Javadoc Plugin-Konfiguration sieht derzeit wie folgt aus: 

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

Alle Hinweise, wie diese Arbeit zu machen?

War es hilfreich?

Lösung

Wie @Stephen erwähnt, ist die Quelldatei für die geerbte Methode muss verfügbar sein und auf dem Weg durch -sourcepath angegeben sein muss. Dies ist in der Javadoc Tool-Dokumentation erläutert:

  

Automatisches Kopieren von Methode Kommentare

     

Das Javadoc-Tool hat die Fähigkeit,   kopieren oder „erben“ Methode Kommentare in   Klassen und Schnittstellen unter dem   folgenden zwei Umstände.   Konstruktoren, Felder und verschachtelt   Klassen nicht erben doc Kommentare.

     
      

  • Automatisch vererben Kommentar zu füllen fehlenden Text - Wenn ein Haupt   Beschreibung oder @return,   @param oder @throws Tag fehlt   von einer Methode Kommentar, die Javadoc   Werkzeug kopiert die entsprechende Haupt   Beschreibung oder Tag-Kommentar von der   Verfahren es überschreibt oder Geräte (wenn   vorhanden), nach dem Algorithmus   unten.

         

    Genauer gesagt, wenn ein @param Tag für einen bestimmten   Parameter fehlt, wird dann den Kommentar   für diesen Parameter aus den kopierten   Methode weiter die Vererbungs   Hierarchie. Wenn ein @throws-Tag für eine   Insbesondere Ausnahme fehlt, die   @throws-Tag wird nur kopiert, wenn das   Ausnahme erklärt wird.

         

    Dieses Verhalten Kontraste mit Version 1.3 und früher, wo die   Vorhandensein einer Haupt Beschreibung oder   Tag alle Kommentare von würde verhindern   vererbt.

    •   

  • Explizit vererben Kommentar mit {@inheritDoc} Tag - Legen Sie die   Inline-Tag {@inheritDoc} in a   Verfahren Haupt Beschreibung oder @return,   @param oder @throws Tag-Kommentar -   das entsprechende vererbten Haupt   Beschreibung oder Tag-Kommentar wird kopiert   in diesem Punkt.

    •   
     

Die Quelldatei für die geerbten   Verfahren braucht nur auf dem Weg zu sein   angegeben von -sourcepath   der doc Kommentar sein eigentlich   zur Verfügung zu kopieren. Weder die Klasse   noch deren Verpackung Bedürfnisse zu übergeben   in der Befehlszeile. Dies steht im Gegensatz   mit 1.3.x und früheren Versionen, in denen   die Klasse sein musste ein dokumentiert   Klasse

So würden Sie die <sourcepath> optionale Konfigurationsparameter der javadoc-Plugin (das die Quellen des Projektes enthält standardmäßig).

By the way, sind <links/> etwas anderes, <links/> verwendet werden, um externe Projekte Querverweise hinzuzufügen. Und tatsächlich, sie sollten nicht für das JDK verwendet werden. Aus konfigurieren Links :

  

Seit 2.6, ein Javadoc API Link, je die JDK-Version von Ihrem Projekt verwendet, wird hinzugefügt. Die Version der Javadoc API wird von dem Wert des erfassten <source/> Parameter in der org.apache.maven.plugins:maven-compiler-plugin (definiert in ${project.build.plugins} oder in ${project.build.pluginManagement}) oder computed über die ausführbare Javadoc-Tool. Wenn Sie auf diesen Link überspringen möchten, müssen Sie konfigurieren <detectJavaApiLink/> false.

     

Hinweis: , wenn Sie eine nicht unterstützte JDK wie 7.0 verwenden, können Sie seine Javadoc API-URL mit der <javaApiLinks/> Parameter, das heißt: 

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

Siehe <links/> Parameter für weitere Informationen.

Angenommen, Sie ein 1,6 source Ebene im Compiler-Plugin konfiguriert, Querverweise Links auf die Java-API funktioniert einfach (Links verweisen auf http://download.oracle.com/javase/6/docs/api/ ), gibt es nichts für den Java-API hinzuzufügen.

  

Weder funktioniert bei mir aus der Box. Ich musste den Abschnitt Links hinzufügen, um die Querverweise Arbeit zu machen.

Schräge. Haben Sie tatsächlich die complier source Ebene angeben, wie dokumentiert? Nur für den Fall, hier ist das, was für mich funktioniert: 

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

Andere Tipps

Ich kann Ihnen keine definitive Antwort geben, aber ich denke, dass das fehlende Stück im Puzzle ist, dass die javadoc Dienstprogramm Bedürfnisse der Lage sein, den Quellcode finden des relevanten externen APIs für javadoc Vererbung an der Arbeit.

Ich hatte eine ähnliche Frage auf Stackoverflow, die mir geholfen, dieses Problem zu lösen besser als die akzeptierte Antwort auf diese questsion: maven-javadoc-Plugin und inheritDoc für Java API Core-Klassen

Zusammenfassung: Um die Javadoc von Java-Core-Klassen zu erben, müssen Sie ihre Quellen entpacken und sie in der Javadoc zu bauen. Die Quellen der Java-Core-Klassen sind in einer src.zip Datei innerhalb der JDK-Distribution zur Verfügung gestellt.

Lizenziert unter: CC-BY-SA mit Zuschreibung
Nicht verbunden mit StackOverflow
scroll top