Padrões de Documentação - JsDoc

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 JsDoc, ferramenta criada para gerar documentação de códigos fontes Javascript 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 Javascript.

Em Javascript estamos utilizando a Herança Parasítica, de maneira similar à descrita por Douglas Crockford.

Cabeçalho de Arquivo

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

       /**
        * 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:

       /**
        * 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. Em Javascript, não há uma declaração exata de variável para definí-la como Global, o que define isso é o escopo em que a mesma foi declarada.

Deve ser documentado da seguinte forma:

       /**
        * 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 nomedavariavel
        * /
        var 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.

       /**
        * 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)
       {
           staticvar = 7;
           return staticvar;
       }

Documentando Classes

A documentação de uma classe deve ser feita informando a qual pacote a mesma pertence. No COREPHP, temos trabalhado com as classes utilizando herança parasítica, da seguinte forma:

       /**
        * 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
        */
       MyClass = function ()
       {
            var self = new Object();
            return self;
       }

Para extender de um outro objeto, basta substituir a linha

            var self = new Object();

por

            var self = new OutraClasseQualquer();

Atributos de Classes

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

       /**
        * 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
        */
       MyClass = function ()
       {
            var self = new Object();
           
           /**
            * Comentário sobre a variável, para que serve, etc
            * @access private
            * @var integer|string
            */
           var firstvar = 6;
           
           /**
            * Comentário sobre a variável, para que serve, etc
            * @access public
            * @var integer|string
            */
           self.firstvar = 6;
           
           return self;
       }

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.

       /**
        * 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
        */
       MyClass = function ()
       {
            var self = new Object();
           
           /**
            * Comentário sobre a variável, para que serve, etc
            * @access private
            * @var integer|string
            */
           var firstvar = 6;
           
           /**
            * Comentário sobre a variável, para que serve, etc
            * @access public
            * @var integer|string
            */
           self.firstvar = 6;
           
           /**
            * Comentário sobre a função, para que serve, etc
            * @access private
            * @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 
            */
           firstFunc = function(param1, param2)
           {
               var staticvar = 7;
               return staticvar;
           }
            
           /**
            * Comentário sobre a função, para que serve, etc
            * @access public
            * @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 
            */
           self.secondFunc = function(param1, param2)
           {
               var staticvar = 7;
               return staticvar;
           }
           
           return self;
       }