¿Cómo puedo hacer el trabajo javadoc herencia para las API externas? (Con Maven2)

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

Pregunta

Cuando una clase anula un método concreto o implementos y método abstracto, el Javadoc se hereda automáticamente a menos que sobrescriba de forma explícita.

O, al menos, la herramienta intenta hacer esto. Parece que no funciona para las API externos con enlaces. Por ejemplo, cuando en mi código implemento java.util.Map, o alguna otra cosa de la JRE, los javadocs no son heredados / copian de los JRE javadocs / apidocs.

En mi caso concreto, yo estoy tratando de configurar esto en el plugin Maven2 Javadoc, pero es lo mismo cuando se ejecuta la herramienta javadoc CLI directamente.

Mi Maven2 Javadoc plugin de configuración actualmente se ve así: 

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

Cualquier punteros sobre cómo hacer este trabajo?

¿Fue útil?

Solución

Como se mencionó @Stephen, el archivo fuente para el método heredado debe estar disponible y debe estar en la ruta especificada por -sourcepath. Esto se explica en la documentación de la herramienta Javadoc:

  

automático Copia del Método Comentarios

     

La herramienta Javadoc tiene la capacidad de   copiar o "heredan" los comentarios del método de   clases e interfaces en el marco del   después de dos circunstancias.   Constructores, campos y anidado   clases hacen comentarios no hereda doc.

     
      

  • Comentario heredan automáticamente a suplir la falta de texto - Cuando un principal   Descripción , o @return,   @param o etiqueta @throws falta   a partir de un comentario método, el Javadoc   herramienta copia del correspondiente principales   descripción o etiqueta de comentario de la   método que anula o implementos (si   los hay), de acuerdo con el algoritmo   a continuación.

         

    Más específicamente, cuando una etiqueta @param para un particular,   parámetro no está presente, entonces el comentario   para ese parámetro se copia del   método de más arriba en la herencia   jerarquía. Cuando una etiqueta para un @throws   en particular excepción no está presente, la   @throws etiqueta se copia sólo si ese   excepción se declara.

         

    Este comportamiento contrasta con la versión 1.3 y anteriores, donde el   presencia de cualquier descripción principal o   etiqueta evitaría todos los comentarios de   siendo heredada.

    •   

  • Comentario explícitamente hereda con la etiqueta {@inheritDoc} - Inserte el   inline etiqueta {@inheritDoc} en una   Descripción principal método o @return,   @param o etiqueta de comentario @throws -   la correspondiente principal heredado   descripción o etiqueta de comentario se copia   en ese lugar.

    •   
     

El archivo de origen para el heredada   método sólo necesita estar en el camino   especificado por -sourcepath para   el comentario de documentación para ser realidad   disponible para copiar. Ni la clase   ni sus necesidades de paquetes a ser transmitidos en   en la línea de comandos. esto contrasta   con 1.3.xy versiones anteriores, en donde   la clase tenía que ser un documentados   clase

Así que lo tienes que utilizar el <sourcepath> opcional de configuración de parámetros del plugin javadoc (que contiene por defecto las fuentes del proyecto).

Por cierto, <links/> son otra cosa, <links/> se utilizan para añadir enlaces de referencias cruzadas a proyectos externos. Y, de hecho, no deben ser utilizados para el JDK. De enlaces Configuración :

  

Desde 2.6, un enlace API Javadoc, dependiendo de la versión del JDK utilizada por el proyecto, se añadió. La versión de la API Javadoc se detecta a partir del valor de la <source/> parámetro en el org.apache.maven.plugins:maven-compiler-plugin (definido en ${project.build.plugins} o en ${project.build.pluginManagement}) o computed a través del ejecutable de la herramienta Javadoc. Si desea omitir este enlace, es necesario configurar <detectJavaApiLink/> para false.

     

Nota: si está utilizando un JDK soportado como 7.0, se podría añadir su URL de la API Javadoc utilizando el <javaApiLinks/> parámetro, es decir: 

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

Consulte <links/> parámetro para más información.

Si se asume que ha configurado un nivel de 1,6 source en el plugin del compilador, referencias cruzadas enlaces a la API de Java simplemente funciona (enlaces apuntan a http://download.oracle.com/javase/6/docs/api/ ), no hay nada que añadir a la API de Java.

  

Ni los trabajos fuera de la caja para mí. He tenido que añadir la sección de enlaces para hacer el trabajo de referencias cruzadas.

extraño. ¿Realmente especificar el nivel source compilador tal como se documenta? Por si acaso, aquí es lo que funciona para mí: 

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

Otros consejos

No te puedo dar una respuesta definitiva, pero creo que la pieza que falta en el rompecabezas es que las necesidades de servicios públicos javadoc sean capaces de encontrar el código fuente de las API externas relevantes para la herencia javadoc al trabajo.

Yo tenía una pregunta similar en StackOverflow, que me ayudó a resolver este problema mejor que la respuesta aceptada de esta questsion: maven-plugin y javadoc-inheritDoc de Java API de las clases básicas

Resumen: Con el fin de heredar el Javadoc de las clases principales de Java, es necesario descomprimir sus fuentes e incluirlos en la construcción de Javadoc. Las fuentes de las clases principales de Java se se proporcionan en un archivo src.zip dentro de la distribución de JDK.

Licenciado bajo: CC-BY-SA con atribución
No afiliado a StackOverflow
scroll top