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}), 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) é necessá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: "function" para Funções "class" para Classes "method" para Métodos "property" para Propriedades de classes "variable" para Variáveis
@version	version-text		Indica para qual versão de produto ou mesmo servidor, que uma determinada funcionalidade requer.

Árvore de páginas

ProtheusDOC

Uso

Marcações aceitas