Javadoc: package.html ou package-info.java

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

package-info.java

PrósMais recentesContrasAbuso de classe - Classes são para código, não apenas para comentários

package.html

PrósExtensão HTML significa que não é códigoDestaque de sintaxe nos editores de IDE / textoContrasNenhum?

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

questionAnswers(1)

yourAnswerToTheQuestion