%cabeçalho para todos os capítulos
%\input{cabecalho}

%\begin{document}

%Opções para o pacote listings
%\input{listingOptions}

\chapter{Javadoc}

\begin{center}
\shabox{
  \begin{Bitemize}
    \item[]\textbf{Quais novidades veremos nesta aula?}
    \item Documentação com javadoc
  \end{Bitemize}
} % \shabox
\end{center}
\bigskip

\section{Javadoc}

Vimos nas últimas aulas que um conceito fundamental em programação
orientada a objeto é a separação clara entre implementação e interface.
Ou seja, um programador que vá usar objetos de uma classe deve se ater à
porção pública da mesma, desprezando detalhes de implementação e as
porções privadas (que não estariam acessíveis de qualquer forma). Deste
modo, passa a ser natural a exigência de documentação de boa qualidade
que permita ao usuário de uma classe saber tudo o que precisa sem que
necessite ler o código que a implementa. Aí entra o \texttt{javadoc}.

O \texttt{javadoc} é um programa que permite extrair, de um arquivo com código
Java, a sua documentação (texto explicativo). Essa documentação é então
formatada em HTML (a mesma linguagem que descreve as páginas da Web) de modo a
facilitar a sua consulta. Assim é possível consultar a documentação de uma
classe sem as distrações presentes sempre que esta está misturada ao código.
Um exemplo disso é que, em sua configuração padrão, o \texttt{javadoc}
processa apenas a documentação das partes públicas de seu código, omitindo
tudo o que é privado.

Para facilitar a vida do programa \emph{javadoc} existem algumas convenções
que devem ser seguidas. A primeira é que apenas comentários iniciados por /**
(e terminados por */) são processados. Também o comentário de cada parte
pública deve precedê-la imediatamente. Vejamos um exemplo simples.

\begin{lstlisting}
public class Quadrado implements FiguraGeometrica
{
  private double lado;
  private String cor;

  public Quadrado(double l, String c)
  {
    lado = l;
    cor = c;
  }

  public double calculaArea()
  {
    return lado*lado;
  }

  public void mudaCor(String c)
  {
    cor = c;
  }
}
\end{lstlisting}

As partes públicas no código acima são:

\begin{enumerate}
\item A própria classe, ou seja todo mundo pode criar objetos baseados nela;
\item O construtor;
\item Os métodos \texttt{calculaArea} e \texttt{calculaPerimetro}.
\end{enumerate}

Cada um desses ítens deveria ser antecedido por um comentário explicando
qual sua função e como ele deve ser usado. Lembrando as convenções de
como demarcar os comentários descritas acima teríamos:

\begin{lstlisting}
/**
 * Uma classe para representar quadrados.
 */
public class Quadrado implements FiguraGeometrica
{
  private double lado;
  private String cor;

  /**
   * Construtor
   * Exige o comprimento do lado e a cor do quadrado.
   */
  public Quadrado(double l, String c)
  {
    lado = l;
    cor = c;
  }

  /**
   * Calcula a área do quadrado baseada no seu lado.
   */
  public double calculaArea()
  {
    return lado*lado;
  }

  /**
   * Altera a cor do quadrado para a cor representada no String c.
   */
  public void mudaCor(String c)
  {
    cor = c;
  }
}
\end{lstlisting}

Uma outra característica interessante do javadoc é que ele possui alguns
marcadores especiais para que possa extrair informações relevantes dos
comentários e formatá-las de modo especial. Os marcadores mais
importantes são:

\begin{itemize}
   \item Marcadores para comentários de classes:
   \begin{itemize}
      \item \texttt{@author}: Descreve o autor do código;
      \item \texttt{@version}: Usado para guardar informação sobre a versão, como
            seu número e data de última alteração.
   \end{itemize}
   \item Marcadores para comentários de métodos:
   \begin{itemize}
     \item \texttt{@param}: usado para descrever os parâmetros, geralmente na forma: \\
           \texttt{@param nome-do-parâmetro descrição}

     \item \texttt{@return}: serve pra descrever o valor devolvido pelo método.
   \end{itemize}
   \item Marcador geral: \texttt{@see}. Pode ser usado em qualquer lugar para
         referenciar uma outra classe ou um método de outra classe; assume
         geralmente uma das duas forma a seguir.\\
         \texttt{@see nome-da-classe} \\
         \texttt{@see nome-da-classe\#nome-do-método}
\end{itemize}

Se usarmos os marcadores descritos acima na nossa classe Quadrado, teremos:

\begin{lstlisting}
/**
 * Uma classe para representar quadrados.
 * @author Paulo Silva
 * @version 1.0, alterada em 10/06/2003
 * @see FiguraGeometrica
 */
public class Quadrado implements FiguraGeometrica
{
  private double lado;
  private String cor;

  /**
   * Construtor
   * @param l double representando o comprimento dos lados
   * @param c String com o nome da cor da figura
   */
  public Quadrado(double l, String c)
  {
    lado = l;
    cor = c;
  }

  /**
   * Calcula a área do quadrado baseada no seu lado
   * @param Não há parâmetros
   * @return área computada
   */
  public double calculaArea()
  {
    return lado*lado;
  }

  /**
   * Altera a cor do quadrado.
   * @param c String com o nome da nova cor
   * @return Não há retorno
   */
  public void mudaCor(String c)
  {
    cor = c;
  }
}
\end{lstlisting}

\begin{figure}[ht]
\begin{center}
\includegraphics[%
  clip,
  width=14cm,
  angle=0]{images/tela.png}
\caption{\label{fig:javadoc}Documentação gerada pelo \texttt{Javadoc}}
\end{center}
\end{figure}

Na figura \ref{fig:javadoc} é apresentada a documentação gerada pelo \texttt{Javadoc} para a classe \texttt{Quadrado}.

É claro que para o marcador \texttt{@see} funcionar, você também deve documentar
a interface usando os padrões de javadoc. Ao documentar a interface você
pode usar os mesmos marcadores usados para classe.

Bom, agora que temos no nosso código documentado de forma adequada, como
podemos gerar a documentação em html? Para isso basta ir ao diretório
com os arquivos \texttt{.java} e digitar

\begin{verbatim}
javadoc -version -author -d doc *.java
\end{verbatim}

A documentação será então gerada e os arquivos resultantes serão
colocados dentro do sub-diretório \texttt{doc} do diretório atual. É claro que o
nome desse diretório pode ser alterado mudando-se a palavra que segue o
\texttt{-doc} presente acima.

Por fim, podemos também documentar as porções privadas de nossas
classes. Para forçar o javadoc a gerar documentação também para a parte
privada basta acrescentar o parâmetro \texttt{-private} na linha de comando acima.

Obs: se desejado, os comentários de javadoc podem conter comandos em HTML.
