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

package-info.javapode conter anotações [package] - não são necessariamente todos os documentos da API.

— Tom Hawtin - defina

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

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

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

@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

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

Alguma razão específica para a sua preferência?

— TheLQ

@ TheLQ: Estou adivinhando anotações de pacotes, pois o compilador tem mais informações para trabalhar; mais acima.

— trashgod

As anotações de pacote são novas para mim e parecem um bom motivo para package-info.java devido ao seu escopo.

— stacker

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

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