Como documentar o código do AMADIS

Da AMADIS

Revisão das 05h12min de 5 de Julho de 2006 por Juliano (discussão | contribs)
(dif) ← Revisão anterior | Revisão actual (dif) | Revisão seguinte → (dif)

Índice

Introdução

Umas das Boas práticas de programação dentro do AMADIS é a documentação do código. No começo da vida de qualquer programador, é mais comum prender-se em tarefas que envolvam aprendizado de novas técnicas. O grande problema está em não se fazer registro dos descobrimentos, testes, criações, etc. Por este motivo este documento é escrito, para o novo desenvolvedor do AMADIS.

Todo código do AMADIS deve ser documentado, e deve-se seguir um padrão do phpDocumentor para fazer isso. Todos os arquivos de classe da AMADIS_API deve conter cabeçalhos que indiquem a que pacote e subpacote elas pertencem.


Escopo

Este artigo contém os padrões de documentação para o AMADIS. Os tópicos abordados são:

  • Introdução do phpDocumentator;
  • Normas de documentação;
  • Cabeçalhos padrão de documentação;

PHPDocumentor

O phpDocumentor é uma ferramenta para documentação utilizado com a linguagem PHP. Ele é similar ao Javadoc, porém escrito em php.

O phpDocumentator pode ser tanto usado na linha de comando (shell) como atraves de uma interface web para criar documentação profissional do codigo PHP de sua aplicação. Ele tem suporte para a linkagem entre arquivos, incluindo a criação de documentos para os usuarios finais, tais como tutoriais, além de criar código destacado com referência para documentação geral de PHP.

As tags para a criação da documentação são inseridas por meio de comentários. O phpDocumentator procura nos arquivos PHP por comentários que sigam a seguinte estrutura chamada de "docblock":

/**
 * Isto é um comentário =)
 **/


O phpDocumentator usa um sistema de templates extensiveis para mudar os comentarios do código fonte em um formato útil para leitura. Esse sistema permite a fácil criação para ler o documento em 15 diferrentes HTML designers, formato PDF, formato Windows Helpfile (CHM), e em XML.


Padrões de Documentação no AMADIS

Todo o código fonte escrito no AMADIS ou que opera junto com a plataforma deve conter um docblock no topo de cada arquivo e um docblock imediatamente acima de cada classe. Caso o arquivo apenas descreva uma classe, não é necessária a documentação do arquivo, apenas da classe. Abaixo estão exemplos desses docblocks.

Arquivos

Cada arquivo PHP no AMADIS deve conter um cabeçalho que possua ao menos os seguintes tags do phpDocumentator:

<codehighlight language="php"> <? /**

* Descriação curta do arquivo
*
* Descrição longa do arquivo (se for necessário)
*
* LICENSE: Licensed under GPL
*
* @license    http://opensource.org/licenses/gpl-license.php GNU Public License
* @version    $Id$
* @since      File available since Release 1.2.0
* @author     Rupert, the Code Monkey <rupert@lec.ufrgs.br>
**/

</codehighlight>

Classes

Cada classe PHP no AMADIS deve conter um cabeçalho que possua ao menos os seguintes tags do phpDocumentator:

<codehighlight language="php"> <? /**

* Descrição curta da classe.
*
* Descrição longa da classe (se existir)
*
* @license    http://opensource.org/licenses/gpl-license.php GNU Public License
* @version    $Id$
* @since      File available since Release 1.2.0
* @author     Rupert, the Code Monkey <rupert@lec.ufrgs.br>
**/

</codehighlight>

Métodos e funções

Cada método ou função PHP no AMADIS deve conter um cabeçalho que possua ao menos os seguintes tags do phpDocumentator:

<codehighlight language="php"> <? /**

* Comentário sobre o funcionamento ou objetivo do método ou função.
*
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
* @version 1.0
* @example  /path/to/example.php  description
**/

</codehighlight>

Além destas informações, todos os argumentos da função devem ser documentados com o tag @argument. Todos os possíveis retornos da função devem ser documentados com a tag @return.

Não é necessário utilizar a tag @access porque a visibilidade do método já é definido em sua declaração.

Se alguma função gerar uma exceção, deve-se declará-la na documentação com a tag @throws.

As tags @example, @license e @see não são obrigatórias, elas são interessantes para incremento de sua documentação e para melhor navegação pelas classes que são correspondentes.

O AMADIS é composto por pacotes, estes se encontram espalhados por diversas pastas, pois o seu desenvolvimento ainda encontra-se de forma plenamente modular. Para isso, deve-se definir na documentação a qual pacote e subpacote cada classe ou arquivo pertence com as tags @package e @subpackage.


O pacote sempre será AMADIS. O subpacote deve identificado na seguinte listagem.


Artigos Relacionados

Links

Ferramentas pessoais
Parceiros
















SourceForge.net Logo

Supported by Cenqua