Acessibilidade, parte 2

Continuando com a postagem anterior, a parte 1 sobre o tema "acessibilidade", e é claro que você já está por dentro do assunto após ter lido todo aquele texto, mas agora vou deixar um de lado a visualização, para falar um pouco sobre navegação, afinal, poder mexer é tão importante quanto poder ver.

Mas antes de tentar dar algumas dicas de navegação, temos que entender o que é a navegação, e qual a importância dela.

Pra começar, se você está vendo esse blog de programação, existe uma enorme possibilidade de você possuir um teclado e um mouse. O que? Está surpreso com essa frase? Estou falando sério, lembre-se de que nem todos os seus possíveis leitores/clientes possuem um teclado e um mouse! Mas voltando a você, provavelmente você está usando o mouse para navegar por esse site, mas vamos fazer um pequeno teste (primeiro leia esse parágrafo, depois faça o teste). Coloque o ponteiro do mouse sobre o relógio do sistema, feche os olhos, não vale roubar, feche os olhos totalmente e tente clicar no link “Início” que está lá em cima, no topo do meu blog, você consegue?

Acho que você não conseguiu, pois ainda está lendo essa postagem, o que podemos entender com esse exercício? O mouse foi criado para quem tem uma visão boa. Mas, vamos fazer outro teste. Fique com os olhos abertos, mas coloque os dois braços atrás da cabeça, como se estivesse sendo abordado pela polícia, agora sem usar as mãos, tente clicar no botão “Início” e depois voltar para essa postagem. Acho que dessa vez você consegue, mas vai ser muito incômodo não é mesmo? Não precisa dizer como você está controlando o mouse, isso não importa muito, apenas precisamos perceber que o mouse foi feito para quem, além de uma boa visão, possui ao menos um braço ou uma boa coordenação motora para poder controlá-lo com outra parte do corpo.

Agora vamos fazer um último teste, esconda seu mouse e tente navegar nesse site. Você consegue? Sim, claro que consegue, mas vai ser um pouco mais chato, nesse caso temos que utilizar a tecla “TAB” que é a tecla utilizada para navegar pelo site sem utilizar um mouse, essa tecla vai passando por cada elemento da página, veremos mais detalhes adiante.

Em suma, um site com uma navegação acessível, atende, diversos tipos de pessoas e equipamentos, não importa se o usuário possui deficiência visual, motora, se ele não possui um mouse ou qualquer que seja o motivo. Mas como fazer isso? Calma, agora que entendemos o problema, podemos pensar em possíveis soluções.

O primeiro passo é eliminar do seu site qualquer menu feito em flash ou similares, por que esses tipos de menus, só são acessados com o mouse, mesmo se você colocar um script para aceitar o teclado, ainda não vai funcionar por que o “componente” precisa estar ativo para que o teclado funcione. Difícil de entender essa parte? Eu explico, vá em algum site de jogos online, que geralmente são feitos em flash ou Java applet, escolha um jogo e deixe a página dele carregar mas assim que você escolher o jogo NÃO CLIQUE NO JOGO, apenas deixe a página dele carregar e tente jogar. Você não vai conseguir, é por que o applet ou flash não está “ativo”, se você pressionar as setinhas cima, baixo, esquerda e direita, você vai movimentar a página e não o personagem do jogo, se você quiser ativar o controle do jogo, vai ter que clicar no applet ou flash, para somente após isso, conseguir utilizar o teclado. Se você possui um menu feito em flash ou applet ou qualquer coisa do tipo, delete-o e crie um novo menu via HTML, pode utilizar imagens, muitas imagens, mas lembre-se do assunto anterior, não deixe seu site muito “pesado”. Além dessa dificuldade, seu leitor/cliente pode tentar acessar o site de um celular ou de um computador um pouco mais antigo que não possua suporte para a ferramenta que você está tentando disponibilizar, nesse caso também vai ficar muito difícil navegar pelo seu site.

Ainda nos menus, mas também no resto do site, se você está tratando algum tipo de evento do mouse via script, tipo  “onmouseover”, “onclick”, “onmouseout”, esse menu ou item só vai funcionar se seu leitor/cliente possuir e conseguir utilizar um mouse, mas se for um deficiente visual, ou alguém que não possua mouse, essa pessoa não conseguirá navegar pela página.

Duas alternativas plausíveis, a primeira é remover esses eventos e menus que capturam o evento do mouse, outra solução é adicionar eventos de teclado! Se você está capturando um “onclick” capture também quando a tecla “barra de espaço” for acionada, se está capturando o “onmouseover” adicione também um evento “onfocus”, se está utilizando o evento “onmouseout”, capture também o evento “onblur”, sempre procure similares para teclado, em todos os eventos de mouse que estiver utilizando.

Outro fator importante para a navegação é a ordem dos elementos, esqueçamos mais uma vez o mouse, desconecte ele e guarde em algum lugar, navegue pela sua página utilizando a tecla “TAB”, você consegue chegar ao conteúdo rapidamente ou tem que passar por milhares de botões e propagandas antes? Se você está demorando mais do que 5 “tabs” para chegar ao conteúdo, EU acho que já é muito, alguns acham até que o primeiro “tab” já deve cair no conteúdo, mas ai você tenta fazer isso nesse blog e vê que não consegue chegar no conteúdo da postagem antes de passar por todo tipo de link, correto? Realmente, mas esse blog não é meu, é do wordpress.com, eu não edito o código fonte do site, apenas o da minha postagem, infelizmente.

Mas como criar uma navegação? Utilizando um comando html simples, o “tabindex”.
Tabindex é um atributo que existe na maioria das tags html, e com ele é possível estabelecer uma ordem de navegação para os objetos, definindo com valores numéricos, de preferência positivos, alguns navegadores aceitam valores negativos, mas não são todos.

Exemplos:

<a href=”x.com.br” tabindex=”1”>aaa</a>
<a href=”x.com.br” tabindex=”2”>bbb</a>
<input type=”submit” value=”ccc” tabindex=”3”/>

No exemplo acima, o primeiro tab vai deixar o link “aaa” selecionado (não vai acionar o link, vai apenas dar o foco para ele), o segundo tab vai marcar o link “bbb”, o terceiro tab vai marcar o botão “ccc”.

Você pode deixar lacunas entre os tabindex, por exemplo, 1-2-3-6-7-9-15-29-30-100, neste caso os tabs vão acessar os objetos na ordem que for definida, se um número não for encontrado, então o próximo é procurado, e assim vai até encontrar um número.

Não é necessário inserir as tabulações na ordem que os objetos estiverem dispostos no código fonte, você pode colocar um tabindex=”1” para um objeto que está no final da página e um tabindex=”2” para um objeto que está no começo, isso não importa, se fizer isso o primeiro tab vai acessar o objeto que está com a tabulação “1” e o segundo tab vai acessar o objeto “2”.

Resumindo o capítulo, quando estiver criando ou editando o código fonte de uma página, invista alguns minutos tentando navegar pelo site sem o mouse e veja se é possível, se não conseguir então será necessário efetuar alguns ajustes.

Assim encerro esta postagem, e para a próxima prepararei uma matéria sobre leitores de tela e a utilidade (ou falta de utilidade) de tabelas em sites acessíveis.

Enjoy!

Performance em aplicações Java. O problema é você!

O título dessa postagem já é um “spoiler”, mas o que eu quero dizer realmente com “O problema é você”?

Antes de sair apontando o dedo para o pessoal de rede dizendo que o servidor não presta ou o cabeamento está cheio de baratas (provavelmente o servidor é ultrapassado e o cabeamento está cheio de baratas), mas antes de culpar o servidor, aponte o dedo para o espelho, e melhore esse código feio que está fazendo!
Pense que em uma aplicação, não é apenas o “front-end” que precisa ser bonito, a área por traz das cortinas tem que ser mais bonita ainda. Você gosta quando precisa arrumar um programa que o código foi feito por um estagiário do período cenozoico? Pois bem, provavelmente o próximo programador que olhar para o seu código vai ter a mesma impressão: “P.q.p! Esse código deve ter passado pelas mãos sujas de um estagiário!”. Particularmente eu não gosto de assinar um código feio, só coloco meu nome em um código depois de arrumá-lo e deixá-lo legível.

IMPORTANTE: Código feio e gambiarra são coisas extremamente diferentes, gambiarras fazem partes da vida de qualquer programador, seja ele estagiário ou especialista, porém só porque precisamos fazer uma gambiarra não significa que devemos deixar o código em hebraico. Mas o que tem a ver código legível com deixar o programa mais rápido?


Tudo!

Uma cultura de “código limpo” e “código bonito” leva a uma outra cultura, de “programa rápido”, pois você se acostuma a fazer um código melhor, que consequentemente, funcionará de forma mais rápida. Além de um fator importante, a performance do programador que for arrumar ou melhorar o programa. Com certeza quem for mexer no código-fonte desse programa vai terminar a alteração muito mais rápido se não precisar utilizar o tradutor do google para traduzir de “hebraico para javanês”. Mas o que, especificamente, pode ser feito para deixar a aplicação mais rápida? Siga os passos abaixo, que verá a diferença.
Em alguns casos, o usuário não perceberá a diferença, mas você sim, porque o servidor vai parar de cair e você vai parar de ser acordado as três da madrugada para dar “stop/start” na aplicação.

Laços FOR
Entenda que “for” convencional é mal, “foreach” e “iterator” são bons. Em um laço for convencional, é necessário criar vários objetos para controle do loop e do próprio conteúdo da lista, e isso consome mais processamento e memória do que um foreach ou iterator, porque esses dois já trabalham de uma forma que, se bem utilizados, não há a necessidade de criar objetos de controle. Exemplo de foreach:

ArrayList<Objeto> lista = new ArrayList<Objeto>(Numeros.CEM);

for(Objeto variavel : lista) {

System.out.println(variável.getNome());

}

Exemplo de Iterator

ArrayList<String> array = new ArrayList<String>(Numeros.CEM);

Iterator<String> it = array.iterator();

while(it.hasNext()) {

System.out.println(it.toString());

}

Métodos dentro de laços 
Isso não se faz, a cada iteração do loop um método de terceiros é consultado. Se o valor não muda, é melhor atribuí-lo à uma variável, diminuindo o tempo de processamento do laço. Exemplo de como não fazer:

 ArrayList lista = new ArrayList();

for (int i = 0; i < lista.size(); i++) {

System.out.println(lista.get(i));

}

Nesse exemplo, de como não fazer, a chamada ao método “lista.size()” será efetuada em cada iteração do laço, que pode ser while ou do..while, e se o laço possuir dez mil iterações, serão dez mil chamadas ao método que contará sempre os dez mil registros da lista.


Exemplo de como se deve fazer, economizando processamento.

ArrayList<String> array = new ArrayList<String>(Numeros.CEM);

int tamanho = array.size();

int x = Numeros.ZERO;

while(x < tamanho) {

}

for (int i = 0; i < tamanho; i++) {

}

Imports não utilizados.
Sempre que passar por uma classe, remova os imports não utilizados, pode ser manualmente ou com o atalho “CTRL+SHIFT+O” do eclipse. Apesar de não parecer, os imports inutilizados ajudam a deixar a classe mais pesada, por que quando ela é compilada (pelo javac), todas as classes importadas são compiladas juntas.
Isso também vale para imports com * no pacote, é bem difícil você utilizar todas as classes de um determinado pacote, e provavelmente você não vai querar compilar todas as classes de um pacote junto com a sua, ou quer?

Objetos e Tipos Primitivos
Sempre que possível, não utilize objetos (Integer, Double, Float) mas sim tipos primitivos (int, double, float) que são mais leves. Quando for trabalhar com faixas numéricas pequenas, utilize também um tipo pequeno, por exemplo o byte para apenas códigos 1, 2, 3, etç. Use o short para faixas de 0 a 32767 (ou negativos nessa mesma faixa). Um objeto exige muito mais espaço na memória do que um tipo primitivo, por exemplo, o int só precisa de uma faixa na memória para guardar o valor da variável, já o Integer precisa de um espaço bem maior, para guardar a classe Integer, que possui além do valor, várias outras variáveis e métodos internos. Quando houver a necessidade de trabalhar com um int que nunca pode ser nulo, impeça o usuário de acionar algum método sem preencher o campo da tela.

Listas sem objeto ou tamanho.
Sempre que utilizar uma lista, indique de que tipo é essa lista, dessa forma economizamos memória e processamento, não sendo necessário criar objetos e fazer o cast em cada item dessa lista.
Sempre defina um tamanho inicial para a lista. Quando não informamos um tamanho para a lista, o compilador entende que seu tamanho inicial será 10. Quando essa lista ultrapassa os 10 itens, o compilador cria uma nova lista com mais 10 itens, ou seja, 20 itens, e copia a primeira lista para a segunda lista, se ela ultrapassar os 20 itens, o compilador cria uma nova lista com mais 10 itens, ou seja, 30 itens, e copia todos os objetos da segunda lista para a terceira lista. Se você não definir um tamanho e sua lista possuir mil objetos, esse processo irá se repetir 100 vezes, consumindo memória e processamento. Para contornar esse problema, sempre defina um tamanho inicial para suas listas, e esse número deve se aproximar do tamanho que a lista terá.
Por exemplo, se eu estiver criando uma lista departamentos de uma empresa, vou criar uma lista com tamanho inicial igual a 100, por que não existem milhares de departamentos em uma empresa. Se eu estiver criando uma lista de funcionários de uma empresa multi-nacional, vou definir um tamanho inicial de 1000 para a minha lista, fazendo isso, mesmo que a lista possua dez mil objetos, eu já diminui o processamento em cem vezes, por que ela não vai precisar ser copiada de 10 em 10, mas sim de 1000 em 1000.


Exemplo de como não fazer:

            ArrayList lista = new ArrayList();

 Exemplo de como se deve fazer:

            ArrayList<Objeto> lista = new ArrayList<Objeto>(Numeros.CEM);

Pesquisas e ordenações em Listas
“Não tente reinventar a roda”, não há a necessidade de criar um algoritmo com laços e variáveis para fazer uma pesquisa ou ordenar uma lista, a Sun já criou formas mais fáceis e leves para isso. Algoritmos como quicksort, bubblesort, binariesort, só são utilizados para aprender lógica de programação e em linguagens estruturadas, em orientação a objetos só se deve recorrer a este tipo de algoritmo em casos “extremamente extremos”, onde não existe nenhuma outra possibilidade de se resolver o problema utilizando a própria linguagem ou o framework.
Para fazer pesquisas, use o MAP (ou similares), que já foi criado para esse tipo de funcionalidade.
Para ordenar uma lista, implemente o Comparator.

Exemplo de MAP.
No próprio for, onde você recupera ou cria os dados, você pode criar um MAP no lugar do List ou ArrayList que já está utilizando. O MAP funciona no esquema “chave / valor”. Na chave você define o termo que será pesquisado, e no valor você insere o objeto inteiro.

Criação de um MAP: 

                Map<Integer, String> mapa = new HashMap<Integer, String>();
                for (Objeto obj : minhaLista) {
                           mapa.put(obj.getCpf(), obj);
                }

Lembre-se de utilizar para “chave” alguma coisa que não se repita, como CPF, por exemplo. Também é possível utilizar algum controle próprio, como números, ou qualquer outra coisa.
Para pesquisar alguma coisa nesse mapa, deve-se verificar se existe algum objeto com a chave informada (containsKey), e se existir, pega esse objeto, simples assim. Nem precisa de loop.

                if(mapa.containsKey(111222333)) {
                          Objeto = mapa.get(111222333);
                }

Para ordenar uma lista, de forma simples e “direta”.

                ArrayList<Objeto> lista = new ArrayList<Objeto>(Numeros.CEM);
                Collections.sort(lista, new Comparator<Objeto>() {
                                public int compare(Objeto r1, Objeto r2) {
                                                if (r1.getIdade() < r2.getIdade()) {
                                                                return Numeros.MENOS_UM;
                                                } else if (r1.getIdade() > r2.getIdade()) {
                                                                return Numeros.UM;
                                                } else {
                                                                return Numeros.ZERO;
                                                }
                                }
                });

Explicando, eu tenho uma lista qualquer e quero ordená-la, então eu utilizo o método sort da classe Collections, esse método precisa da lista que será ordenada e de um “Comparator” dessa lista, você pode criar uma classe ou método que retorne esse comparator ou pode cria-lo na hora, como fiz no exemplo acima.
O comparator precisa ter um método compare que recebe dois objetos, do mesmo tipo de objeto da lista, esse método compare deve retornar -1 se o primeiro objeto for menor, ou deve retornar 1 se o primeiro objeto for maior, ou deve retornar zero se os dois forem iguais. Você que define o que vai decidir se um objeto é maior ou menor, você pode comparar o que quiser, qualquer uma das variáveis do objeto, o que o sort precisa é dos retornos -1, 1 e 0.

Strings e Constantes.
Utilizar strings diretamente nos métodos é mau. Utilizar constantes em uma classe própria para constantes é bom.
Exemplo de como não fazer:
                     String texto = “alguma coisa”;
                     int retorno = 0;

Exemplo de como fazer:
       Classe de constantes (ViewConstants, Números, etç.) String texto = ViewConstants.TEXTO;
onde TEXTO está marcado como “public static final String” na classe de constantes Int retorno = Numeros.ZERO; onde ZERO está marcado como “public static final int” na classe de constantes numéricas Se você tem uma classe muito popular, que é acessada muitas vezes, e dentro dessa classe tem varias variáveis e objetos, sempre que a classe for acessada novos objetos e variáveis são criados, ocupando mais e mais memória do servidor. Para evitar isso, crie uma classe para armazenar todas as strings e constantes de sua aplicação, mas lembre-se de sempre marcar suas constantes com “static final”, dessa forma as variáveis serão criadas apenas uma vez, e utilizadas por todas as classes da aplicação, sem que mais memória seja utilizada.

Concatenação de Strings
Sempre que é utilizada a concatenação de Strings, novos endereços da memória são separados para essa tarefa, e esses endereços só são liberados quando o método ou a classe morre, se o garbage collector fizer seu trabalho assim que o método ou classe morrer, dessa forma, para evitar o uso excessivo de memória, aconselha-se utilizar o StringBuffer para esse trabalho.

Exemplo de como não fazer:
                    String texto = “texto1”;
                    texto += “ ”;
                    texto += “texto2”;

Exemplo de como se deve fazer, economizando memória. 
                   StringBuffer texto = new StringBuffer();
                   texto.append(“texto1”);
                   texto.append(“ ”);
                   texto.append(“texto2”);

No “exemplo de como não fazer”, se você concatenar a string “A” com a string “B”, e depois com a string “C”, e com a string “D” e assim por diante, você estará ocupando um largo espaço na memória, pois a cada concatenação, uma nova String é criada, para armazenar o resultado da sua soma. O processo é similar ao da copia da lista, explicado anteriormente.
Utilizando o StringBuffer, você gasta apenas o endereço que o StringBuffer já está utilizando, não sendo necessário criar várias outras variáveis de apoio.

Comentários Javadoc e in-line
Essa prática não desempenha nenhum papel fundamental na performance do sistema, mas garante uma boa performance dos programadores que estiverem mexendo no código, conforme mencionado nas primeiras linhas desse post, pois um método complicado que estiver bem comentado sempre será mais fácil de entender, não precisando perder tempo para descobrir o que um IF, um for, uma variável ou o próprio método está representando.
Os comentários, podem ser colocados na assinatura do método, em forma de javadoc e também antes de cada código, utilizando comentários de linha.
Saiba mais sobre javadoc aqui. Exemplo: /**
*
  * Nome: Fazer alguma coisa
  * Propósito: Esse método recebe um “Objeto” devidamente preenchido e verifica se
  * deve ser gravado completo ou se deve ser feita uma gravação individual no banco de dados.
  * @param Objeto, esse objeto precisa que a variável idade de cada indivíduo esteja preenchida,
  * recomenda-se utilizar a validação na tela, não deixando chegar nenhum nulo no java
  *
*/
public void doSomethig(Objeto param) {
      //Verifica se é para gravar todos ou um de cada vez
      if(param.getIdade() > ClasseSistema.getXpto()) {
               ServiceImplQualquer.gravarInformacoes(param);
      } else {
             //Grava os objetos um a um, mas precisa que a idade de cada objeto
            //esteja preenchida, utilizando a validação da tela
               for (ObjetoX objetoX : param.getLista()) {
                      ServiceImplQualquer.gravarUmDeCada(objetoX);
              }
    }
}

Sem medo do JavaDoc

O “JavaDoc” falando em termos gerais, é um gerador de documentação que a sun criou para ser utilizado por programadores, para documentar todo o código fonte visível de uma aplicação. Fazer o javadoc da aplicação que você está fazendo é muito importante, tanto para você quanto para outros programadores que utilizarão o seu programa, por exemplo, se você estiver fazendo uma biblioteca (jar), se não tiver javadoc quem for utilizar o seu jar estará perdido, e até você mesmo poderá se perder quando estiver melhorando ou fazendo algum ajuste no código, eu mesmo esqueço qualquer lógica que eu tenha criado a mais de algumas horas, por isso todo código que eu faço é muito bem comentado e documentado, isso não me toma muito tempo e é bom fazer isso enquanto o método está sendo criado, por que a regra de negócio dos métodos e das classes ainda estão na memória (na sua memória). Vamos para um exemplo prático!
Para poder comprovar o  efeito do javadoc, você vai precisar de uma ide. Se você já manipulou arquivos em java, precisou em algum momento definir delimitadores de diretórios “/” para unix e “\” para windows. Mas você não precisa fazer um código pra descobrir o sistema operacional do usuário do seu programa, o java já te informa tudo o que você precisa do sistema operacional utilizado pelo usuário, com o código System.getProperty(), esse método recebe uma String, que indica qual propriedade do sistema operacional você quer, mas eu não sei o que eu tenho que informar, eu sei apenas que eu quero um “separador de diretórios”, então o que fazer? Escreva na sua IDE, dentro de algum método java.lang.System.getProperty(“”), esse método não vai nos servir pra nada, por que não informamos qual a propriedade do sistema que queremos, mas não se desespere, a sun faz JavaDoc. Selecione o método getProperty e aperte a tecla F2 (eclipse) ou apenas coloque o mouse sobre o método até aparecer uma janelinha conforme abaixo. Está ai, tudo o que o método faz, explicado em cada detalhe, da até pra navegar.
Se descer mais um pouco a barra de rolagem vai ver alguns links na seção “See Also“, clique no link “getProperties()“, um outro javadoc vai aparecer, mas agora o javadoc do método getProperties, contendo todas as possíveis variáveis que devem ser informada no método getProperty, no nosso caso seria a “file.separator”, mas olha como tem várias variáveis que podemos utilizar, legal né? Essa não é a unica forma de ver um javadoc, da também para ver de uma forma geral em um navegador. Quando você termina o seu projeto, se ele estiver com todos os javadocs criados, você pode “exportar” essa documentação para o formato html e ele fica exatamente dessa forma: http://download.oracle.com/javase/6/docs/api/ Esse é o javadoc da JRE/JDK, a documentação, da linguagem java. Seu programa pode ter uma documentação exatamente igual a essa, se você documentar os métodos corretamente. Percebeu a importância do javadoc? Apenas os javadocs de objetos “public” são exportados ou ficam visíveis, mas sempre documente todos os seus métodos mesmo private, afinal nunca se sabe quando você vai precisar dessa documentação, e existe a opção de exportar a documentação de objetos private e protected também, mas vamos ver isso mais adiante. Um javadoc não difere em nada de um comentário de bloco /* comentário de bloco  */ a diferença é que ele começa com dois asteriscos /** javadoc */, até a cor muda, se você não alterou as cores da sua ide, um comentário normal, começando com um asterisco, tem a cor diferente de um comentário javadoc, que começa com dois asteriscos. Um javadoc aceita tags HTML, e eu aconselho escrever o javadoc como se estivesse fazendo uma página web mesmo, mas não precisa de comandos complexos, ficar alinhando criando div, nada disso, vamos ser simplistas, limite-se a usar negrito <b></b>, itálico <i></i>, sublinhado <u></u>, tabelas se necessário <table><tr><td></td></tr></table>, parágrafos <p></p> e quebras de linha <br>, mais que isso já é desnecessário. Os links são criados automaticamente com tags próprias. O javadoc tem alguns comandos próprios para definirmos coisas como versão, autor, descrever os parametros e o retorno, explicar as exceções que são lançadas, entre outros. Todos os comandos javadoc começam com @. Exemplo prático

/** 
* Método principal 
* <p>Esse método executa alguma ação</p> 
* @param args, um vetor de argumentos que podem ser informados 
* @author coreerror 
* @exception Vai ser lançada uma NullPointerException 
* @version 1.0.1 
* @return Vai ser retornada uma lista de String 
*/
public static void main(String[] args) {
java.lang.System.getProperty(“file.separator”);
}

Esse comentário azul antes do método é o javadoc, nele eu coloquei o nome do método, coloquei também em um parágrafo informando o que o método faz, expliquei os parâmetros com a tag @param, falei que fez esse método com a tag @autor, expliquei as exceções com a tag @exception, indiquei a versão do método com @version e disse também o que o método irá retornar com @return. Não repare que o javadoc não tem nada a ver com o método, isso ai é só pra exemplificar, eu sei que o método não retorna nada e não lança nenhuma exception. Se você colocar o mouse sobre a palavra main (o nome do método), vai ver esse comentário sendo exibido como um javadoc:

Existe também a tag @see, essa tag deve ser utilizada quando você quer que o javadoc de outro método ou classe seja visto, e um link vai ser criado automaticamente para o método ou classe que você indicou, lembra que no javadoc do System.getProperty você clicou no link getProperties? É exatamente isso, sempre coloque @see para as dependencias do seu método, para as classes que devem ser informadas por parâmetro para seu método, se ele receber objetos, ou em caso de classes, coloque @see para os construtores e para oturas classes que trabalham em conjunto com ela, etç. Quando você quer referenciar um método de alguma classe no javadoc você não deve utilizar o ponto @see System.getProperty, mas sim um “sustenido“, também conhecido como “jogo da velha” @see System#getProperty, isso também vale para referenciar métodos ou variáveis que estiverem na mesma classe @see #outroMetodo() @see #algumaVariavel

/** 
* @see System 
* @see System#getProperty(String) 
* @see #getClass() 
*/
public static void main(String[] args) {
java.lang.System.getProperty(“file.separator”);
}

Se você quer criar um link em algum lugar que não seja a seção “See Also” você também pode, por exemplo, se na parte que você está explicando o que o método faz e como ele funciona você já quiser ir linkando as classes e métodos envolvidos, basta utilizar o comando {@link Classe}, com chaves e tudo, no lugar da palavra “Classe” você coloca o nome da classe ou da Classe#Método.

/** 
* Método principal 
* <p>Esse é um método da classe {@link MainClass} e 
* acessa a classe {@link System}</p> 
*/ 
public static void main(String[] args) {
java.lang.System.getProperty(“file.separator”);
}

Para exportar o javadoc e criar um site igual ao da sun que está linkado mais acima você pode ir da forma menos chata, pela IDE, clicar com o botão direito sobre o projeto e selecionar a opção Exportar, depois escolhe Java/JavaDoc na caixa de diálogos que irá abrir, nas telas seguintes seleciona as opções da documentação, onde os arquivos serão salvos, quais classes participarão desse documento, se você quer a documentação dos componentes public, protected, private ou apenas a documentação dos pacotes, da pra selecionar os jars envolvidos na sua aplicação e várias outras opções. Mas se você é guerreiro, pode ir pelo console e utilizar o comando “javadoc”, dentro da pasta onde suas classes estão. Ex.:

javadoc -d doc c:\home\codeerror\projetoTeste\src\*.java

Todos as opções que podem ser selecionadas através da IDE também podem ser indicadas na linha de comando, são inúmeras opções, sugiro digitar no console “javadoc -help” para analisar as que você precisa. Agora que você está craque em javadoc, vai colocar em cada código que fizer, vou colocar uma pequena tabela abaixo com os comandos mais relevantes e pra que eles servem.

@author	Nome de quem fez o código
@category	Você pode criar categorias para seus códigos, como “utilidades” ou “maipulação” ou “services”, etç,
@deprecated	Informa se esse método está depreciado, ou seja, irá deixar de existir na próxima versão do programa
@exception	Indica as exceções que podem ser lançadas pelo método/Classe
@param	Explica o parâmetro, deve ser criado um @param para cada parametro recebido pelo método. Tente explicar detalhadamente, como por exemplo “Informar o objeto X com todas as variáveis preenchidas” ou “informar um numero de 0 a 10?
@return	Explica o que será retornado pelo método, indique também as possíveis variações de retorno, como “pode retornar verdadeiro se 1 for menor que 2 ou falso se 2 for maior que 1?.
@see	Cria um link de referência para outra classe ou método
@since	Esse é para controle de versão, aqui você informa quando o método foi adicionado na classe, ou quando a classe foi adicionada ao pacote
@throws	Similar a @exception
@version	Aqui você pode indicar a versão da classe ou do método
{@link XX}	Cria um link para uma classe ou método, o nome da classe ou método deve ser colocado no lugar das letras “XX”

Enjoy!