Como faço para fazer o javadoc herança trabalho externo APIs?(com Maven2)

Question

Quando uma classe substitui um método concreto ou implementa e método abstrato, o Javadoc é automaticamente herdada, a menos que explicitamente substituído.

Ou, pelo menos, a ferramenta tenta fazer isso.Parece que ele não funcionar externos ligados APIs.Por exemplo, quando eu na minha código de implementar java.util.Map, ou algo do JRE, o javadocs não são herdadas/copiado do JRE javadocs/apidocs.

No meu caso específico, eu estou tentando configurar isso no Maven2 Javadoc plugin, mas é o mesmo quando eu executar o javadoc ferramenta CLI diretamente.

Meu Maven2 Javadoc plugin de configuração atualmente se parece com isso:

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

Quaisquer indicações sobre como fazer esse trabalho?

Answer 1

Como o @Stephen mencionado, o arquivo de origem para o método herdado deve estar disponível e deve ser o caminho especificado pela -sourcepath.Isso é explicado na ferramenta Javadoc documentação:

A Cópia automática do Método Comentários

A ferramenta Javadoc tem a capacidade de copiar ou "herdar" método de comentários em classes e interfaces sob o a seguir duas circunstâncias.Construtores, campos e aninhados classes não herdam doc comentários.

• Herdam automaticamente comentário para preencher em falta texto - Quando um principal descrição, ou @return, @param ou @throws tag está em falta a partir de um método de comentário, o Javadoc ferramenta de cópias correspondentes principal descrição ou tag de comentário da método substitui ou implementa (se qualquer um), de acordo com o algoritmo abaixo.

  Mais especificamente, quando um @param marca para um determinado parâmetro estiver ausente, então o comentário para esse parâmetro é copiado a partir da o método mais a herança hierarquia.Quando um @throws marca para um exceção específica é falta, o @throws tag é copiado somente se que exceção é declarada.

  Este comportamento contrasta com a versão 1.3 e anteriores, onde o a presença de qualquer descrição principal ou tag seria impedir que todos os comentários sendo herdadas.

• Explicitamente herdar comentário {@inheritDoc} marca - Inserir o tag inline {@inheritDoc} em um método descrição principal ou @return, @param ou @throws tag de comentário -- o correspondente herdadas principal descrição ou tag de comentário é copiado em que lugar.

O arquivo de origem para o herdada o método precisa ser apenas sobre o caminho especificado pelo -sourcepath para o doc comentário, na verdade, ser disponível para cópia.Nem a classe nem o seu pacote precisa ser passado em na linha de comando.Isso contrasta com 1.3.x e versões anteriores, onde a classe tinha que ser um documentado classe

Então você teria que usar o <sourcepath> opcional parâmetro de configuração do javadoc plugin (que contém, por padrão, as fontes do projeto).

---

Pelo caminho, <links/> são outra coisa, <links/> são usados para adicionar a referência cruzada de links para projetos externos.E, na verdade, eles não deveriam ser usados para o JDK.A partir de Configurar links:

Desde 2.6, um Javadoc API do vínculo, consoante o JDK versão usada pelo seu projeto, vai ser adicionado.A versão da API Javadoc é detectada a partir do valor da <source/> parâmetro na org.apache.maven.plugins:maven-compiler-plugin (definido no ${project.build.plugins} ou em ${project.build.pluginManagement}), ou calculado através da Ferramenta Javadoc executável.Se você deseja ignorar este link, você precisará configurar <detectJavaApiLink/> para false.

Nota: se você estiver usando um sem JDK como 7.0, você pode adicionar a sua API Javadoc url usando o <javaApiLinks/> parâmetro, por exemplo:

<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 obter mais informações.

Supondo que você configurou um 1.6 source nível em que o compilador plugin, referências cruzadas links para a API Java só funciona (links apontam para http://download.oracle.com/javase/6/docs/api/), não há nada a acrescentar para a API Java.

---

Nem funciona fora da caixa para mim.Eu tive que adicionar a seção de links para fazer o cruzamento de trabalho.

Estranho.Será que você realmente especificar o compilador source nível como documentado?Em qualquer caso, aqui está o que funciona para mim:

  <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

Não posso te dar uma resposta definitiva, mas acho que a peça que falta no quebra -cabeça é que o javadoc utilidade precisa ser capaz de Encontre o código -fonte das APIs externas relevantes para a herança Javadoc funcionar.

Answer 3

Eu tive uma pergunta semelhante no StackOverflow, que me ajudou a resolver esse problema melhor do que a resposta aceita desta busca: Maven-Javadoc-Plugin e HeritDoc para Java API Core Classes

Resumo:Para herdar o Javadoc das classes Java Core, você precisa descompactar suas fontes e incluí -las na construção javadoc. As fontes das classes principais Java são fornecidas em um src.zip Arquivo dentro da distro JDK.