Esta é uma área dedicada a documentação do programa / função / método. Contém comentários explicando a sua finalidade, data de criação, parâmetros, retornos e alterações efetuados.
Existem dois tipos de cabeçalho, conforme mostrado a seguir:
Cabeçalho de fonte:
Acima podemos observar a área de identificação de uma função da Linha Microsiga Protheus.
Note que ela é formada por tags que podem ser facilmente identificadas. Estas tags são utilizadas para integrar a documentação do código com o site de documentação da Linha Microsiga Protheus.
Na tabela abaixo destacamos a função de cada uma das tags:
{Protheus.doc} | Identifica o inicio do bloco de documentação. Deve ser precedido do nome da função ou método e no parágrafo seguinte deve ter a descrição completa do bloco. |
@param | Parâmetros de entrada, listados na ordem de passagem. Exemplo: //---------------------------------------------------------- /*/{Protheus.doc} FWTeste1() Função teste @param cFederalId Informe. @param nErro Retorna. @param aIDs Retorna. /*/ //---------------------------------------------------------- Function FWteste1(cFederalId,nErro,aIDs) |
@protected | Se inserida indica que a função tem uso restrito pela GDP criadora e não pode ser reaproveitada em customizações e/ou integrações. //---------------------------------------------------------- /*/{Protheus.doc} FWTeste1() Função teste @protected /*/ //---------------------------------------------------------- Function FWteste1(cFederalId,nErro,aIDs) |
@author | Autor ou revisor do bloco //---------------------------------------------------------- /*/{Protheus.doc} FWTeste1() Função teste @author Eduardo Riera /*/ //---------------------------------------------------------- Function FWteste1(cFederalId,nErro,aIDs) |
@version | Versão da Linha de produto Microsiga Protheus em que o bloco teve inicio. Utilize a nomenclatura definida pela GDP de Framework, exemplo: //---------------------------------------------------------- /*/{Protheus.doc} FWTeste1() Função teste @version MP11.5 /*/ //---------------------------------------------------------- Function FWteste1(cFederalId,nErro,aIDs) |
@build | Versão mínima da Build do Application Server que o bloco é suportado. //---------------------------------------------------------- /*/{Protheus.doc} FWTeste1() Função teste @build 7.00.100812P - Sep 1 2010 /*/ //---------------------------------------------------------- Function FWteste1(cFederalId,nErro,aIDs) |
@deprecated | Se inserida indica que a função não possui mais manutenção e/ou foi substituída por outra, tendo seu uso depreciado. Recomenda-se assim a substituição pela nova função. //---------------------------------------------------------- /*/{Protheus.doc} FWTeste1() Função teste @deprecated /*/ //---------------------------------------------------------- Function FWteste1(cFederalId,nErro,aIDs) |
@see | Indica as funções que devem ser observadas pelo desenvolvedor antes do uso. “Veja também”. //---------------------------------------------------------- /*/{Protheus.doc} FWTeste1() Função teste @see FWTeste2,FWTeste3,FWTeste4 /*/ //---------------------------------------------------------- Function FWteste1(cFederalId,nErro,aIDs) |
@since | Data de criação da rotina //---------------------------------------------------------- /*/{Protheus.doc} FWTeste1() Função teste @since 9/10/1995 /*/ //---------------------------------------------------------- Function FWteste1(cFederalId,nErro,aIDs) |
@return | Indicador do retorno da função //---------------------------------------------------------- /*/{Protheus.doc} FWTeste1() Função teste @return ExpL: indica se a rotina foi executada corretamente. /*/ //---------------------------------------------------------- Function FWteste1(cFederalId,nErro,aIDs) |
@todo | Indicativo de função incompleta ou com pendências de desenvolvimento //---------------------------------------------------------- /*/{Protheus.doc} FWTeste1() Função teste @todo proteger a função de chamadas por customização. /*/ //---------------------------------------------------------- Function FWteste1(cFederalId,nErro,aIDs) |
@sample | Exemplo de uso do bloco |
@obs | Observação complementar ao bloco. |