Diagnóstico das documentações
Como o ProtheusDoc possui uma convenção documentada, é importante que ele seja utilizado com um padrão, para que assim possa ser usufruído todos os recursos disponíveis como:
- Comandos & recursos
- Documentação HTML
- Hover de documentações
- Tabela de documentações
- Entre outros...
Assim todos poderão aproveitar as features implementadas e as que ainda estão por vir, sem que a extensão precise se preocupar em como cada usuário está utilizando o ProtheusDoc.
Para auxiliar o desenvolvedor a utilizar o ProtheusDoc segundo a convenção da TOTVS, foi implementado na extensão um diagnóstico (validador) de sintaxe e valores não informados ou inválidos.
| Atributo | Mensagem | Causa | Alternativas |
|---|---|---|---|
| Header | Descrição ou identificador da documentação não informado | A sintaxe do cabeçalho pode estar inválida, ou não foi informado a descrição da documentação | Ajustar a sintaxe ou informar uma descrição válida |
@type |
Tipo do identificador não informado. Deve ser function, class ou method | O atributo @type é obrigatório, e deve ser informado somente os tipos válidos |
Utilizar um dos seguintes tipos: function, class ou method. Ou o snippet @type, que irá sugerir os tipos válidos |
@type |
Tipo do identificador inválido. Deve ser function, class ou method | O atributo @type deve ser informado somente com os tipos válidos |
Utilizar um dos seguintes tipos: function, class ou method. Ou o snippet @type, que irá sugerir os tipos válidos |
@author |
Autor não foi informado | Autor vazio ou com o valor default | Informar o autor no atributo. Para não utilizar este atributo, considere-o na configuração protheusDoc.marcadores_ocultos
|
@param |
Nome do parâmetro não foi informado | Nome do parâmetro vazio ou com valor default | Necessário informar o nome do parâmetro |
@param |
Tipo do parâmetro não informado ou inválido | O tipo do parâmetro deve ser informado com um tipo válido | Somente são aceitos os tipos: numeric, character, date, codeblock, logical, array, object, variadic, decimal, json e variant
|
@param |
Descrição do parâmetro não foi informada | Descrição do parâmetro vazio ou com valor default | Necessário informar a descrição do parâmetro |
@return |
Tipo do retorno não informado ou inválido | O tipo do retorno deve ser informado com um tipo válido | Somente são aceitos os tipos: numeric, character, date, codeblock, logical, array, object, variadic, decimal, json e variant
|
@return |
Descrição do retorno não foi informada | Descrição do retorno vazio ou com valor default | Necessário informar a descrição do retorno |
@history |
Data do histórico não foi informada ou é inválida | Data não foi informada ou não é um formato válido de data | Necessário informar uma data para o histórico |
@history |
Autor do histórico não foi informado | Autor vazio ou com o valor default | Informar o autor no atributo |
@history |
Descrição do histórico não foi informada | Descrição do histórico vazio ou com valor default | Necessário informar a descrição do histórico |
@since |
Data da documentação não foi informada ou é inválida | Data vazia ou não é um formato válido de data | Informar a data no atributo. Para não utilizar este atributo, considere-o na configuração protheusDoc.marcadores_ocultos
|
@version |
Versão da documentação não foi informada ou é inválida | Versão vazia ou com o valor default | Informar a versão no atributo. Para não utilizar este atributo, considere-o na configuração protheusDoc.marcadores_ocultos
|
@example |
Atributo @example informado mas não utilizado |
Exemplo vazio ou com o valor default | Informar o Exemplo no atributo |
@see |
Atributo @see informado mas não utilizado |
"Veja mais" vazio ou com o valor default | Informar um valor no atributo |
@obs |
Atributo @obs informado mas não utilizado |
Observação vazia ou com o valor default | Informar uma observação no atributo |
@link |
Atributo @link informado mas não utilizado |
Link vazio ou com o valor default | Informar um Link no atributo |
Importante: Os valores default adicionados pelos assistentes da extensão também são validados ex.:
param_type,return_description, etc.
Também é diagnosticado pela extensão, atributos ProtheusDoc obrigatórios e importantes que estão faltando.
| Atributo | Mensagem | Alternativas |
|---|---|---|
@type |
Não foi definido o tipo da documentação | Utilize o Snippet @type para definir o tipo da documentação |
@author |
Não foi definido o autor desse identificador | Utilize o Snippet @author para definir o autor da documentação ou caso não queira utilizar este atributo, considere-o na configuração protheusDoc.marcadores_ocultos
|
@since |
Não foi definido a data de criação deste identificador | Utilize o Snippet @since para definir a data de criação da documentação ou caso não queira utilizar este atributo, considere-o na configuração protheusDoc.marcadores_ocultos
|
É possível desabilitar as validações de duas formas: por atributo ou geral.
Dessa forma não será validado a sintaxe ou se os valores dos atributos não foram informados ou estão inválidos.
Para desativar a validação de um atributo opcional específico, adicione-o na configuração protheusDoc.marcadores_nao_validar.
Obs.: Os atributos @author, @since e @version só não serão validados caso estejam na configuração protheusDoc.marcadores_ocultos.
Veja mais sobre essas configurações na Wiki Configurações.
Caso não deseje que a extensão faça os diagnósticos nas documentações ProtheusDoc, basta desativar na configuração protheusDoc.valida_atributos.
Veja mais sobre essa configuração na Wiki Configurações.
Importante: Os diagnósticos do ProtheusDoc não impedem que um fonte seja compilado.
Importante: Caso tenha dúvidas da estrutura de um atributo, utilize o snippet deste, ou consulte a convenção do ProtheusDoc.
Importante: Recomendamos não utilizar o caractere
@nas descrições das documentações, pois este é um caractere especial usado para identificar atributos do ProtheusDoc. O uso de@pode acarretar em quebras inesperadas e apresentar inconsistências na validação de algum atributo.
Caso encontre algum problema por conta dessa feature, ou perceba que algum Warning apresentado não está correto, fique a vontade para abrir uma issue e nos reportar o problema para que possamos avaliar o caso.