Criando documentação java de sua aplicação

A maioia dos desenvolvedores iniciantes não conhecem algo chamado Javadoc! Isso é primordial para se ter um bom código.  Javadoc é uma ferramenta para gerar documentação em formato HTML a partir de seus comentários no código fonte.

Comentar o código fonte é muito importante, mas se além de comentar o código, o desenvolvedor gerar o javadoc, ele e sua equipe terão um suporte maior no decorrer do desenvolvimento pois terão um material de referência padronizado e fácil de utilizar. Muitas dúvidas poderão ser sanadas simplemente consultando o javadoc.

As páginas de documentação do java, tais como as que você pode ver em http://java.sun.com/j2se/1.4.2/docs/api/index.html, foram geradas com javadoc.

Faça um teste. Crie um projeto qualquer no eclipse (ou tanto faz...) e nele, crie uma classe chamada Teste. Nesta clase, comente da seguinte forma:

/**
* Classe que imprime Alo Mundo na tela
* @author fulano
*
*/
public class Teste {
/**
* Método principal, responsável por imprimir Alo Mundo na tela
* @param args
* @author fulano da silva
*/
public static void main(String[] args) {
System.out.println("Alo mundo");
}
}

Repare que a forma de se documentar é um pouco diferente (/** para iniciar o javadoc e */ para finalizar). Enfim, feito isso, vá para o prompt de comando, e vá para o diretório no qual o codigo fonte do seu projeto se encontra e de o comando:

javadoc -d c:\html *

Ele vai gerar a documentação em c:\html! Veja os resultados.

O Eclise e o netbeans geram javadoc facilmente. Existem N parametros para customizar sua documentação. Veja mais em: http://java.sun.com/j2se/javadoc/index.jsp

O Faq do javadoc está em http://java.sun.com/j2se/javadoc/faq/index.html.

Enjoy.