Javadoc: package.html ou package-info.java

230

Ao tentar criar comentários Javadoc no nível do pacote, qual é o método preferido? O que você faz?

package-info.java

  • Prós
    • Mais recentes
  • Contras
    • Abuso de classe - Classes são para código, não apenas para comentários

package.html

  • Prós
    • Extensão HTML significa que não é código
    • Destaque de sintaxe nos editores de IDE / texto
  • Contras
    • Nenhum?

Para mim, eu sempre usei o Package.html. Mas eu estou querendo saber se é a escolha correta.

java javadoc TheLQ
fonte
46
package-info.javapode conter anotações [package] - não são necessariamente todos os documentos da API.
Tom Hawtin - defina
52
Eu não qualificaria o package-info.java como abuso de uma classe. É um arquivo de origem java (possui uma extensão de arquivo ".java"), mas não é um arquivo de classe porque não contém uma declaração de classe. E, de fato, ele não pode conter uma declaração de classe porque "informações do pacote" não é um nome de classe legal.
scrubbie
19
Outro motivo para usar o package-info.java em vez do package.html pode ser que o .java não implique um formato de saída específico da documentação. Por exemplo, você pode exibir o javadoc como LaTeX ou como um arquivo PDF. Dependendo da implementação do compilador javadoc, isso pode causar problemas no caso .html.
honeyp0t
3
Na verdade, Scrubbie - embora você deva estar certo, acho que você pode especificar classes privadas de pacotes lá. :-( Eu concordo com seu sentimento, porém, usando package-info.javapara Javadoc e anotações não é um abuso de classe.
mjaggard
2
@JonasN ver stackoverflow.com/a/14708381/751579 (Eu sei que você teve este problema há 3 anos, mas talvez alguém precisa a ponta agora)
davidbak

Respostas:

269

package-info.java: "Este arquivo é novo no JDK 5.0 e é preferido em relação ao package.html." - javadoc - O Java API Documentation Generator

Adendo: A grande diferença parece ser anotações de pacotes . Há um pouco mais de justificativa nas declarações do pacote 7.4 .

Adendo: O recurso de anotação também é mencionado aqui e aqui .

Adendo: Veja também Para que serve package-info.java? .

trashgod
fonte
3
Alguma razão específica para a sua preferência?
TheLQ
2
@ TheLQ: Estou adivinhando anotações de pacotes, pois o compilador tem mais informações para trabalhar; mais acima.
trashgod
3
As anotações de pacote são novas para mim e parecem um bom motivo para package-info.java devido ao seu escopo.
stacker
6
Edite a resposta um pouco mais: explique "anotação de pacote" - uma anotação que deve ser aplicada a todas as classes de um pacote ou de outra forma aos pacotes como um todo. O link tech.puredanger.com foi o único a realmente explicar por que eu deveria me importar. Dito isto, é um link bom e útil.
Roboprog
5
usando package-info.java, você pode usar {@link} e outros doclets. Quando você vincula uma classe java.lang, quando o javadoc é gerado, você obtém automaticamente o {@link} apontando para o javadoc online da classe que corresponde ao jdk que você está usando; O ide também pode ajudar a detectar links incorretos ao refatorar a refatoração.
Luigi R. Viggiano