Marcar informações geradas automáticas como warning

[izacsc]

Muitas vezes quando estamos fazendo a documentação apertamos o atalho de geração de documentação e esquecemos de preencher o conteúdo.

Marcar como warning propriedades de descrição que estejam com o valor gerado automático.

[AlencarGabriel]

Olá @izacsc ,

muito interessante sua solicitação, hoje o TDS tem esse comportamento como um "marcador" de linha quando o conteúdo do ProtheusDoc está inválido.

Vou avaliar sua solicitação e volto a informar. Obrigado novamente por sua colaboração!

[izacsc]

Por nada!

Eu me lembro dessa funcionalidade do TDS mas as vezes acabava atrapalhando. No setor onde eu trabalhava, nós colocávamos uma propriedade customizada ( @project ) e todos os cabeçalhos ficavam com erro. A ideia aqui ( pelo menos pra mim ) é mostrar o que foi gerado automático e ainda não foi preenchido, como a descrição da função, de parâmetros e de retornos.

[AlencarGabriel]

Sim, entendi sua questão.

Imaginando como seria vejo que validaria o conteúdo mesmo, mas somente das propriedades que eu trato, pois na Documentação do ProtheusDoc no TDN tem inúmeras outras propriedades que não tratei por considerar "desnecessárias".

[AlencarGabriel]

Olá @izacsc ,

acha interessante essa análise das inconsistências do ProtheusDoc ser somente para o fonte aberto, ou avaliar a workspace inteira?

[izacsc]

Opa, tá corrido aqui rs.

Acredito que no só fonte aberto. E talvez um comando pra analisar a workspace inteira. Analisar tudo deve ficar muito custoso.

Abraço

[AlencarGabriel]

@izacsc , finalizei a implementação dos diagnósticos do ProtheusDoc, poderia instalar essa versão em seu ambiente e verificar se atende as necessidades?

protheusdoc-vscode-0.6.0.zip

Obs.: Não implementei ainda a validação da Workspace, vou deixar para fazer posteriormente.

[izacsc]

Boa tarde! A ideia é essa mesmo. Só não foi implementado pra descrição da função:

[AlencarGabriel]

Opa,

então, eu até implementei pra descrição. Porém pelo visto só detectei se não está informada. Já ajusto aqui.

Coloquei validação de vários atributos (type, param, return, since, author e history) e também caso estejam faltantes como @type e @author.

[AlencarGabriel]

Segue a versão com a descrição corrigida:

protheusdoc-vscode-0.6.0.zip

[izacsc]

Ah, eu ia comentar justamente isso... Eu só validaria o que foi colocado.

Aqui foi por opção que eu não quis documentar o resto...

Mas o negócio tá começando a ficar complexo rs Mas poderia estar atrás de uma opção para escolher quais atributos são obrigatórios.

Mas tá ficando muito bom

[izacsc]

Mais um pequeno ponto rs
Você tá validando o formato do que tá escrito. Apesar de ser interessante, tem gente que tem outros padrões.

Então pra todos os outros que não seguem esse padrão de descrição de conteúdo, ele apresentaria erro também.

Abraço

[AlencarGabriel]

Então, toda a extensão é baseada na convenção documentada pela própria TOTVS (https://tdn.totvs.com/display/tec/ProtheusDOC)

Esse tipo de situação causaria colateriais em diversos pontos da extensão como: Documentação HTML, Hover do Identificador, etc... Pois todos estes funcionam conforme a estrutura padrão.

Ai como é uma coisa fora do padrão fica difícil tratar.

Posso fazer uma coisa para contornar isso, criar uma configuração para definir quais atributos não serão validados. O que acha?

[izacsc]

Sim, eu entendo. Mas raramente a convenção é seguida ao pé da letra rs

Acho que criar a configuração para validar é uma boa. Assim que começar a usar a extensão pode escolher não ver um monte de erros numa base que não esteja padronizada.

Pergunta, isso desativaria a verificação do preenchimento automático?

[AlencarGabriel]

Pois é, infelizmente em muitos casos não são seguidas mesmo e podem causar problemas que só serão identificados no futuro.

Quanto a sua pergunta, eu faço a validação do arquivo inteiro para verificar se alem dos valores padrões (ou vazios) a sintaxe do ProtheusDoc de alguns atributos essenciais está correta.

Nessa configuração que sugeri, no seu caso você poderia configurar para não validar o atributo @param. Isso não afetaria as outras validações, somente as deste atributo.

[AlencarGabriel]

Olá @izacsc ,

finalizei os ajustes em todos os atributos e adicionei as configurações conforme conversamos.

Se puder validar essa versão, eu agradeço.

protheusdoc-vscode-0.6.0.zip

Ah, fiz uma Wiki somente sobre este recurso https://github.com/AlencarGabriel/ProtheusDoc-VsCode/wiki/Diagnóstico-das-documentações, lá eu explico as validações que são feitas e as configurações relacionadas.

Qualquer coisa só me falar.

Aguardo teu feedback.

[AlencarGabriel]

Implementado na versão 0.7.0.