Histórico da Página
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
...
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 | @todo | 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.