Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

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

O ProtheusDOC, é uma forma estruturada de escrever comentários, sobre funções, classes, métodos ou qualquer outro elemento de um programa-fonte Adv/PLAdvPL, que descreve a utilização deste elemento.

...

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 ou não por marcadores especiais. 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

...

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çãoParâmetrosMúltiplosDescrição da marcação

@accessLevel

accessLevel-text Nível de acesso.
@authorname-text 

Texto com o nome do autor.

@buildbuild-text Indica qual a versão do servidor requerido (similar a "@version").
@countrycountry-text Indica para qual país o elemento foi programado.
@databasedatabase-text Compatibilidade com base de dados.
@defvaluedefvalue-text Indica o valor padrão da propriedade.
@descriptiondescription-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.

@exampleexample-textSimCria uma entrada no tópico “Exemplos”.
@history (TDS11.3)date-text,
username-text,
description-text
SimHistórico de alterações no código-fonte.
@sampleexample-textSimO mesmo que "@example". 
@languagelanguage-text Idioma para o qual elemento está customizado.
@linklink-textSimCria 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.
@obsobs-textSimAdiciona uma observação.
@paramparameter-name
[ , parameter-type]
[ , description ]
SimAdiciona uma especificação de parâmetro (de função ou método), identificando-o como parameter-name. 
@proptypeproptype-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.
@returnreturn-type description Especifica o retorno (de função ou método).
@sourcesource-text Indica o código fonte.
@systemOpersystemOper-text Indica qual o Sistema Operacional requerido.
@seesee-textSimAdiciona uma entrada “Veja também”.
@sincesince-text Identifica a partir de quando, uma determinada funcionalidade foi implementada.
@tabletable-name
[ , another-table-name ]*
 Identifica quais tabelas são utilizadas pela classe, método ou função.
@todotodo-textSimIdentifica uma tarefa a ser realizada.
@typetype-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
@versionversion-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

Image Added

E marque a opção "Desabilitar parser ProtheusDoc". Será exibida uma tela para confirmar a opção, clique em "Sim" para confirmar.

Image Added

Para retornar ao estado inicial, apenas desmarque a opção novamente.