Como manter atualizados os exemplos de código nos javadocs

Estou trabalhando em uma pequena biblioteca que fornece implementações de métricas básicas e bem conhecidas de strings. Principalmente para minha própria educação. Assim, o desenvolvimento acontece sempre que tenho um pouco de tempo livre.

Por isso, automatizei a maioria dos processos para poder lançar uma versão sempre que trabalhar nela sem muito esforço. No entanto, manter o documento Java ainda é um fardo, pois inclui exemplos.

À medida que a API evolui, tenho que verificar manualmente cada exemplo repetidamente. Existe uma maneira melhor de fazer isso?

Eu considerei mover a documentação e os exemplos para um projeto separado (por exemplo, Tutorial do Caliper ) para que ele possa ser re-fatorado e compilado junto com o código regular. No entanto, isso afasta a documentação da classe em questão.

Então sim. Eu gostaria de ter meu bolo e comê-lo também. : D

 * <h2>Tokenization</h2>
 * 
 * Tokenization cuts up a string into tokens e.g.
 * <code>chilperic ii son of childeric ii</code> is tokenized into
 * <code>[chilperic, ii, son, of,
 * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing
 * the individual tokens e.g.
 * <code>[ch,hi,il,il,lp,pe,er,ri,ic, ii, so,on, of, ch,hi,il,ld,de,er,ri,ic, ii]</code>
 * <p>
 * 
 * <pre>
 * <code>
 * {@code
 *  return new StringMetricBuilder()
 *          .with(new SimonWhite<String>())
 *          .tokenize(new Whitespace())
 *          .tokenize(new QGram(2))
 *          .build();
 * }
 * </code>
 * </pre>
 * 
 * <p>

Se o acima exposto também abstrato. Este é um exemplo de documentação. Atualmente, estou adicionando construtores estáticos conforme recomendado pelo Effective Java, por exemplo, Tokenizers.createQGram(2)enquanto deprecia o método construtor. Cada vez que faço algo assim, tenho que atualizar o código de exemplo acima e verificar se ele ainda funciona.

Isso pode não responder à sua pergunta - dependendo de quanto é um 'requisito' ter esses exemplos em sua documentação.

Talvez você possa fazer um ângulo diferente: forneça exemplos em seus testes JUnit. (Talvez até um pacote como com.examples) O problema com o código nos comentários é que seu IDE irá ignorá-lo, na maioria das vezes. Mas seu IDE validará o código em seus testes JUnit. Ao fazer isso, você garante que os exemplos de código estejam 'corretos' - os testes não serão compilados ou simplesmente falharão se você não os tiver atualizado.

Não sou um assistente de Javadocs, mas pode haver uma maneira de vincular a documentação do arquivo de origem ao arquivo JUnit com o código de exemplo. Eu realmente não saberia por onde começar nisso. Um pesquisador superficial me mostrou a @seeetiqueta . Eu testei em um projeto, mas não testei em um javadoc real depois que ele foi gerado.

Definitivamente, isso exigiria um pouco de pesquisa inicial, mas eu realmente acho que você estaria melhor a longo prazo se seus exemplos de código estivessem realmente sendo compilados.

Como uma meta abrangente, você também pode adicionar cobertura de código ao executar seus exemplos de JUnit. Dessa forma, você saberia rapidamente quanto de sua base de código é abordada por seus exemplos.