O objetivo do ProtheusDOC é autodocumentar os programas-fontes escritos em AdvPL.
O ProtheusDOC, é uma forma estruturada de escrever comentários, sobre funções, classes, métodos ou qualquer outro elemento de um programa-fonte AdvPL, que descreve a utilização deste elemento.
Inicialmente os documentos serão gerados no formato HTML através de modelos customizáveis.
Estes modelos serão criados utilizando-se da tecnologia desenvolvida pela Apache Velocity.
A estrutura básica é formada por um bloco de comentários, com um identificador especial no seu início (/*/{Protheus.doc} para o AdvPL e {/{Protheus.doc} para o 4GL), seguido de seu identificador, um comentário sucinto, seguido pelo seu tipo (@type) e opcionalmente por outros marcadores especiais.
A marcação de tipo (@type) é obrigatória, pois é possível existirem nomes de funções, métodos, classes, etc. duplicados e é necessário diferenciá-los.
Observe que o identificador precisa se exatamente o nome da função ou o nome da classe, em caso de serem funções ou classes, respectivamente, ou o nome da classe seguido pelo nome do nome do método separados por "::" em caso de métodos de uma classe, por exemplo nomeDaClasse::New.
Algo semelhante a:
/*/{Protheus.doc} areaQuad
Efetua o cálculo da área de alguns quadriláteros.
@type function
@author José Silva
@since 20/11/2012
@version P10 R4
@param nBase, numérico, Medida do lado ou da base
@param [nAltura], numérico, Medida da altura
@param [nBaseMenor], numérico, Medida da base menor (trapézios)
@return numérico, Área calculada
/*/
User Function areaQuad(nBase, nAltura, nBaseMenor)
...
Uso
Adicione um bloco de comentário do ProtheusDOC no elemento que você deseja descrever em seu programa-fonte.
Você pode adicionar um comentário rapidamente utilizando a combinação, CTRL + ALT + D, mantendo o cursor sobre o nome da função, por exemplo.
Em seguida, para iniciar o assistente de geração do ProtheusDOC, clique em “Arquivo” > “Novo” > “Outras...”. Expanda a seção “TOTVS Tools”, escolha a opção “ProtheusDoc Generator” e clique em “Avançar >” (Next >).
Localize e selecione o programa-fonte que será documentado em seguida clique em “Avançar >” (Next >).
Clique em “Concluir” (Finish) para gerar a documentação utilizando o template padrão e o local padrão de exportação (C:\export).
Localize a pasta de exportação. Ela apresentará a mesma estrutura do projeto onde o programa-fonte está localizado.
Abra o arquivo HTML em seu navegador preferido para ler a documentação gerada.
Caso deseje, você pode criar um template customizado adicionando, removendo e/ou alterando a estrutura utilizando o modelo do Velocity.
*IMPORTANTE* O arquivo do template deve estar com o encoding UTF-8.
O arquivo pdoc.vm do template padrão pode ser obtido neste anexo.
Ao gerar a nova documentação, selecione o template customizado e/ou defina um local alternativo para a exportação da documentação.
Da mesma forma anterior, localize a pasta de exportação alternativa.
Abra o arquivo HTML em seu navegador preferido para ler a documentação customizada que foi gerada.
Marcações aceitas
As marcações aceitas pelo ProtheusDOC até o momento são:
| Marcação | Parâmetros | Múltiplos | Descrição da marcação |
|---|---|---|---|
@accessLevel | accessLevel-text | Nível de acesso. | |
| @author | name-text | Texto com o nome do autor. | |
| @build | build-text | Indica qual a versão do servidor requerido (similar a "@version"). | |
| @country | country-text | Indica para qual país o elemento foi programado. | |
| @database | database-text | Compatibilidade com base de dados. | |
| @defvalue | defvalue-text | Indica o valor padrão da propriedade. | |
| @description | description-text | Cria uma entrada de descrição, para melhor detalhamento da funcionalidade. | |
| @deprecated | deprecated-text | Texto com comentários sobre a depreciação, como por exemplo, motivo e alternativa que deve ser utilizada. | |
| @example | example-text | Sim | Cria uma entrada no tópico “Exemplos”. |
| @history (TDS11.3) | date-text, username-text, description-text | Sim | Histórico de alterações no código-fonte. |
| @sample | example-text | Sim | O mesmo que "@example". |
| @language | language-text | Idioma para o qual elemento está customizado. | |
| @link | link-text | Sim | Cria uma ligação (link) para o target especificado (ver notas). O atributo label será apresentado ao desenvolvedor no lugar da URI e é opcional. Esta marcação deve ser utilizada como complemento nas demais marcações. |
| @obs | obs-text | Sim | Adiciona uma observação. |
| @param | parameter-name [ , parameter-type] [ , description ] | Sim | Adiciona uma especificação de parâmetro (de função ou método), identificando-o como parameter-name. |
| @proptype | proptype-text | Indica o tipo da propriedade. | |
| @protected | Indica que o método deve ser visto com escopo de “não publico”. | ||
| @readonly | Indica que a propriedade é apenas de leitura. | ||
| @return | return-type description | Especifica o retorno (de função ou método). | |
| @source | source-text | Indica o código fonte. | |
| @systemOper | systemOper-text | Indica qual o Sistema Operacional requerido. | |
| @see | see-text | Sim | Adiciona uma entrada “Veja também”. |
| @since | since-text | Identifica a partir de quando, uma determinada funcionalidade foi implementada. | |
| @table | table-name [ , another-table-name ]* | Identifica quais tabelas são utilizadas pela classe, método ou função. | |
| @todo | todo-text | Sim | Identifica uma tarefa a ser realizada. |
| @type | type-text | Identifica o tipo do ProtheusDoc que está sendo documentado:
| |
| @version | version-text | Indica para qual versão de produto ou mesmo servidor, que uma determinada funcionalidade requer. |
Preferências
Caso seja necessário, por algum motivo, existe a opção de desabilitar o parser do ProtheusDoc.
Clique em Janela > Preferências... > Developer Studio Editor > Performance
E marque a opção "Desabilitar parser ProtheusDoc". Será exibida uma tela para confirmar a opção, clique em "Sim" para confirmar.
Para retornar ao estado inicial, apenas desmarque a opção novamente.
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas