ProtheusDOC

O objetivo do ProtheusDOC autodocumentar os programas-fontes escritos em Adv/PL.

O ProtheusDOC, uma forma estruturada de escrever comentrios, sobre funes, classes, mtodos ou qualquer
outro elemento de um programa-fonte Adv/PL, que descreve a utilizao deste elemento.
Inicialmente os documentos sero gerados no formato HTML atravs de modelos customizveis.
Estes modelos sero criados utilizando-se da tecnologia desenvolvida pela Apache Velocity.
A estrutura bsica formada por um bloco de comentrios, com um identificador especial no seu incio (/*/{Prot
heus.doc}), seguido de um comentrio sucinto, seguido ou no por marcadores especiais. Algo semelhante a:
/*/{Protheus.doc} areaQuad
Efetua o clculo da rea de alguns quadrilteros.

@author Jos Silva

@since 20/11/2012
@version P10 R4

@param nBase, numrico, Medida do lado ou da base

@param [nAltura], numrico, Medida da altura
@param [nBaseMenor], numrico, Medida da base menor (trapzios)

@return numrico, rea calculada

/*/
User Function areaQuad(nBase, nAltura, nBaseMenor)
...

Uso
Adicione um bloco de comentrio do ProtheusDOC no elemento que voc deseja descrever em seu
programa-fonte.
Voc pode adicionar um comentrio rapidamente utilizando a combinao, CTRL + ALT + D, mantendo o cursor
sobre o nome da funo, por exemplo.

Em seguida, para iniciar o assistente de gerao do ProtheusDOC, clique em Arquivo > Novo >
Outras.... Expanda a seo TOTVS Tools, escolha a opo ProtheusDoc Generator e clique em
Avanar > (Next >).

Localize e selecione o programa-fonte que ser documentado em seguida clique em Avanar > (Next >).

Clique em Concluir (Finish) para gerar a documentao utilizando o template padro e o local padro de
exportao (C:\export).

Localize a pasta de exportao. Ela apresentar a mesma estrutura do projeto onde o programa-fonte est
localizado.

Abra o arquivo HTML em seu navegador preferido para ler a documentao 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 padro pode ser obtido neste anexo.

Ao gerar a nova documentao, selecione o template customizado e/ou defina um local alternativo para a
exportao da documentao.

Da mesma forma anterior, localize a pasta de exportao alternativa.

Abra o arquivo HTML em seu navegador preferido para ler a documentao customizada que foi gerada.

Marcaes aceitas
As marcaes aceitas pelo ProtheusDOC at o momento so:
Marcao

Parmetros

@accessLevel
@author

Descrio da marcao
Nvel de acesso.

name-text

Texto com o nome do autor.

@build

Indica qual a verso do servidor

requerido (similar a "@version").

@country

Indica para qual pas o elemento foi

programado.

@database

Compatibilidade com base de

dados.

@description

Cria uma entrada de descrio,

para melhor detalhamento da
funcionalidade.

@deprecated

deprecated-text

Texto com comentrios sobre a

depreciao, como por exemplo,
motivo e alternativa que deve ser
utilizada.

@example

Cria uma entrada no tpico

Exemplos.

@sample

O mesmo que "@example".

@language

Idioma para o qual elemento est

customizado.

@link

Cria uma ligao (link) para o target

especificado (ver notas). O atributo
label ser apresentado ao
desenvolvedor no lugar da URI e
opcional. Esta marcao deve ser
utilizada como complemento nas
demais marcaes.

@obs

Adiciona uma observao.

@param

parameter-name parameter-type
description

@protected
@return

Indica que o mtodo deve ser visto

com escopo de no publico.
return-type description

@systemOper
@see

@todo

Especifica o retorno (de funo ou

mtodo).
Indica qual o Sistema Operacional
requerido.

see-text

@since

@table

Adiciona uma especificao de

parmetro (de funo ou mtodo),
identificando-o como
parameter-name.

Adiciona uma entrada Veja

tambm.
Identifica a partir de quando, uma
determinada funcionalidade foi
implementada.

table-name [ , another-table-name ]
*

Identifica quais tabelas so

utilizadas pela classe, mtodo ou
funo.
Identifica uma tarefa a ser
realizada.

@version

Indica para qual verso de produto

ou mesmo servidor, que uma
determinada funcionalidade requer.