Padrões de Documentação - PHPDoc

From COREPHP

Documentação por comentários

A documentação por comentários vem sendo utilizada já há bastante tempo pelos programadores de todo o mundo, como uma forma de facilitar a compreensão de um código criado.

Existem padrões, como o JavaDoc, que se firmaram no mercado e receberam implementações em outras linguagens de programação além do Java.

É o caso do PHPDoc, ferramenta criada para gerar documentação de códigos fontes PHP baseado no padrão JavaDoc.

Este será o padrão utilizado no COREPHP, e deve ser implementado em todos os arquivos de Controle e Modelo que estejam codificados em PHP.

Cabeçalho de Arquivo

Os arquivos devem receber um cabeçalho automático, declarado ao início do arquivo, que conterá os seguintes elementos:

   <?php
   
       /**
        * Comentário descritivo sobre o objetivo/funcionalidade do arquivo. Ex:
        * "Este é o Controle de Turmas, responsável pela criação, edição, e
        * gerenciamento de turmas e alunos inscritos nas mesmas"
        *  
        * @author  Nome do autor <email@doautor.com>
        * @version numerodaversao
        * @package nomedopacote
        */
   
   ?>

O cabeçalho pode conter ainda:

   <?php
   
       /**
        * Comentário descritivo sobre o objetivo/funcionalidade do arquivo. Ex:
        * "Este é o Controle de Turmas, responsável pela criação, edição, e
        * gerenciamento de turmas e alunos inscritos nas mesmas"
        *  
        * @author     Nome do autor <email@doautor.com>
        * @version    numerodaversao
        * @package    nomedopacote
        * @subpackage nomedosubpacote
        * @todo       item que ainda está pendente
        * @todo       item que ainda está pendente
        */
   
   ?>

Documentando Variáveis Globais

A documentação de variáveis globais serve para mapear o uso da mesma, tanto na declaração dela, quanto no uso interno por algum método/função.

Deve ser documentado da seguinte forma:

   <?php
   
       /**
        * Comentário descritivo sobre o objetivo/funcionalidade do arquivo. Ex:
        * "Este é o Controle de Turmas, responsável pela criação, edição, e
        * gerenciamento de turmas e alunos inscritos nas mesmas"
        *  
        * @author     Nome do autor <email@doautor.com>
        * @version    numerodaversao
        * @package    nomedopacote
        * @subpackage nomedosubpacote
        * @todo       item que ainda está pendente
        * @todo       item que ainda está pendente
        */
   
       /**
        * Variável global
        * @global tipodavariavel $GLOBALS["nomedavariavel"]
        */
        $GLOBALS["nomedavariavel"] = "";
   
   ?>

Documentando Funções

A documentação de função deve ser feita logo antes da sua declaração, apresentando os parâmetros a serem passados e o tipo de retorno da função.

   <?php
   
       /**
        * Comentário descritivo sobre o objetivo/funcionalidade do arquivo. Ex:
        * "Este é o Controle de Turmas, responsável pela criação, edição, e
        * gerenciamento de turmas e alunos inscritos nas mesmas"
        *  
        * @author     Nome do autor <email@doautor.com>
        * @version    numerodaversao
        * @package    nomedopacote
        * @subpackage nomedosubpacote
        * @todo       item que ainda está pendente
        * @todo       item que ainda está pendente
        */
   
       /**
        * Comentário sobre a função, para que serve, etc
        * @param string $param1 descrição do parâmetro 1, que deve ser do tipo string
        * @param string $param2 descrição do parâmetro 1, que deve ser do tipo string
        * @return integer 
        */
       function firstFunc($param1, $param2 = 'optional')
       {
           $staticvar = 7;
           return $staticvar;
       }
   
   ?>

Documentando Classes

A documentação de uma classe deve ser feita informando a qual pacote a mesma pertence.

   <?php
   
       /**
        * Comentário descritivo sobre o objetivo/funcionalidade do arquivo. Ex:
        * "Este é o Controle de Turmas, responsável pela criação, edição, e
        * gerenciamento de turmas e alunos inscritos nas mesmas"
        *  
        * @author     Nome do autor <email@doautor.com>
        * @version    numerodaversao
        * @package    nomedopacote
        * @subpackage nomedosubpacote
        * @todo       item que ainda está pendente
        * @todo       item que ainda está pendente
        */
   
       /**
        * Comentário sobre a Classe, para que serve, etc
        * @package nomedopacote
        * @subpackage nomedosubpacote
        */
       class myclass
       {
       }
   
   ?>

Atributos de Classes

A documentação dos atributos da classe é feita declarando-se logo acima da mesma a visibilidade e o tipo dela.

   <?php
   
       /**
        * Comentário descritivo sobre o objetivo/funcionalidade do arquivo. Ex:
        * "Este é o Controle de Turmas, responsável pela criação, edição, e
        * gerenciamento de turmas e alunos inscritos nas mesmas"
        *  
        * @author     Nome do autor <email@doautor.com>
        * @version    numerodaversao
        * @package    nomedopacote
        * @subpackage nomedosubpacote
        * @todo       item que ainda está pendente
        * @todo       item que ainda está pendente
        */
   
       /**
        * Comentário sobre a Classe, para que serve, etc
        * @package nomedopacote
        * @subpackage nomedosubpacote
        */
       class myclass
       {
           /**
            * Comentário sobre a variável, para que serve, etc
            * @access private
            * @var integer|string
            */
           private $firstvar = 6;
       }
   
   ?>

Métodos de Classes

A documentação dos métodos é similar à de funções, com a diferença que deve ser feita dentro da classe.

   <?php
   
       /**
        * Comentário descritivo sobre o objetivo/funcionalidade do arquivo. Ex:
        * "Este é o Controle de Turmas, responsável pela criação, edição, e
        * gerenciamento de turmas e alunos inscritos nas mesmas"
        *  
        * @author     Nome do autor <email@doautor.com>
        * @version    numerodaversao
        * @package    nomedopacote
        * @subpackage nomedosubpacote
        * @todo       item que ainda está pendente
        * @todo       item que ainda está pendente
        */
   
       /**
        * Comentário sobre a Classe, para que serve, etc
        * @package nomedopacote
        * @subpackage nomedosubpacote
        */
       class myclass
       {
           /**
            * Comentário sobre a variável, para que serve, etc
            * @access private
            * @var integer|string
            */
           private $firstvar = 6;
       
           /**
            * Comentário sobre a função, para que serve, etc
            * @param string $param1 descrição do parâmetro 1, que deve ser do tipo string
            * @param string $param2 descrição do parâmetro 1, que deve ser do tipo string
            * @return integer 
            */
           function firstFunc($param1, $param2 = 'optional')
           {
               $staticvar = 7;
               return $staticvar;
           }
       }
   
   ?>