Come faccio javadoc lavoro eredità per le API esterne? (Con Maven2)

Question

Quando una classe sovrascrive un metodo concreto o di attrezzi e metodo astratto, Javadoc è ereditato automaticamente se non esplicitamente sovrascritto.

O, almeno lo strumento cerca di fare questo. Sembra che non funziona per le API esterni collegati. Per esempio, quando ho nel mio codice implemento java.util.Map, o qualcos'altro dalla JRE, i javadocs non vengono ereditate / copiati dalle JRE javadocs / apidocs.

Nel mio caso specifico, sto cercando di configurare questo nel plugin Maven2 Javadoc, ma è lo stesso quando si esegue direttamente lo strumento Javadoc CLI.

Il mio Maven2 Javadoc plugin di configurazione attualmente appare così:

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

Le eventuali indicazioni su come fare questo lavoro?

Answer 1

Come accennato @Stephen, il file di origine per il metodo ereditato deve essere disponibile e deve essere sul percorso specificato da -sourcepath. Questo è spiegato nella documentazione strumento Javadoc:

  

automatico Copia del Metodo Commenti

     

Lo strumento Javadoc ha la capacità di   copiare o "Eredita" Metodo commenti   classi e le interfacce sotto la   dopo due circostanze.   Costruttori, campi e annidato   classi fanno commenti di documentazione non eredita.

     

  

• Commento automaticamente ereditano per riempire mancante testo - Quando un principale   Descrizione o @return,   @param o tag @throws manca   da un commento metodo, il Javadoc   strumento copia il corrispondente principali   descrizione o tag commento dal   metodo sovrascrive o attrezzi (se   qualsiasi), secondo l'algoritmo   qui di seguito.

       

  In particolare, quando un tag @param per un particolare   parametro è mancante, quindi il commento   per tale parametro è copiato dal   metodo ulteriormente l'eredità   gerarchia. Quando un tag per un @throws   particolare eccezione è mancante, la   tag @throws viene copiato solo se tale   eccezione è dichiarata.

       

  Questo comportamento contrasta con la versione 1.3 e precedenti, dove la   presenza di una descrizione principale o   tag impedirebbe tutti i commenti da   essere ereditato.

  

• commento esplicito ereditare con etichetta {@inheritDoc} - Inserire il   tag in linea {@inheritDoc} in un   Metodo Descrizione principale o @return,   @param o tag @throws commento -   il corrispondente principale ereditato   descrizione o tag commento viene copiato   in quel punto.

  

     

Il file di origine per il ereditata   metodo deve essere solo sul percorso   specificato da -sourcepath   il commento di documentazione per essere realmente   a disposizione per copiare. Né la classe   né le sue esigenze pacchetti da passare in   sulla riga di comando. questo contrasta   con 1.3.xe versioni precedenti, in cui   la classe doveva essere un documentati   Classe

Quindi, si avrebbe dovuto utilizzare il <sourcepath> facoltativa la configurazione dei parametri del plugin javadoc (che contiene di default i sorgenti del progetto).

---

A proposito, <links/> sono un'altra cosa, <links/> vengono utilizzati per aggiungere link di riferimento incrociati a progetti esterni. E in realtà, non dovrebbero essere utilizzati per la JDK. Da link Configurazione :

  

Dal 2.6, un collegamento Javadoc API, a seconda della versione JDK utilizzata dal progetto, sarà aggiunto. La versione delle API Javadoc viene rilevata dal valore della <source/> parametro nella org.apache.maven.plugins:maven-compiler-plugin (definito in ${project.build.plugins} o in ${project.build.pluginManagement}) o Computed tramite l'eseguibile Javadoc Tool. Se si desidera saltare questo link, è necessario configurare <detectJavaApiLink/> a false.

     

Nota: se si utilizza un JDK supportato come 7.0, è possibile aggiungere l'URL Javadoc API utilizzando il <javaApiLinks/> parametro, vale a dire:

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

     

Fare riferimento a <links/> parametro per ulteriori informazioni.

Supponendo avete configurato un livello di 1.6 source nel plugin compilatore, riferimenti incrociati collegamenti alle API Java funziona proprio (collegamenti punto a http://download.oracle.com/javase/6/docs/api/ ), non v'è nulla da aggiungere per l'API Java.

---

  

Né i lavori fuori dalla scatola per me. Ho dovuto aggiungere la sezione link per far funzionare riferimenti incrociati.

Strano. Avete in realtà specificare il livello source compilatore come documentato? Solo nel caso, qui è ciò che funziona per me:

  <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

non posso dare una risposta definitiva, ma penso che il pezzo mancante del puzzle è che le esigenze di utilità javadoc siano in grado di trovare il codice sorgente delle API esterni rilevanti per javadoc eredità al lavoro.

Answer 3

ho avuto una domanda simile su StackOverflow che mi ha aiutato a risolvere questo problema in maniera migliore di quanto la risposta accettata di questo questsion: Maven-javadoc-plugin e inheritDoc per le classi di base API Java

Riepilogo: Al fine di ereditare il Javadoc da classi di base Java, è necessario decomprimere le loro fonti e includerli nella build Javadoc. Le fonti delle classi di base Java sono sono forniti in un file src.zip all'interno della distro JDK.