Help Insight Delphi

Olá, leitores!

Veremos neste artigo um recurso muito poderoso e muito simples de ser utilizado, porém muito pouco explorado pela comunidade. Nosso tema de hoje será o Help Insight do Delphi, ele nos ajuda a documentar e facilitar o uso de métodos, variáveis, constantes, enums…

📥 Repositório com exemplos

O projeto de exemplo, pode ser encontrado e baixado em nosso GitHub no seguinte link: https://github.com/Code4Delphi/help-insight-delphi

▶️ Vídeo de demonstração

🚀O QUE É HELP INSIGHT?

Help Insight (informações de ajuda), um recurso do IDE do Delphi que exibe um popup com uma breve descrição sobre o identificador (classe, procedure, function, variável, constante, enumerado…) a qual o cursor do mouse está posicionado no Editor de Códigos. Também é possível invocar o Help Insight pressionando as teclas CTRL + SHIFT + H

HELP INSIGHT PADRÕES

Por padrão, o IDE do Delphi gera automaticamente e exibe dados básicos dos identificadores, com as seguintes informações:

Para function ou procedure, é exibido também o(s) parâmetro(s) e o valor de retorno:

Tudo isso é gerado automaticamente em tempo de edição, ou seja, sem necessitar que o código seja compilado.

CUSTOMIZANDO O HELP INSIGHT

Embora as informações geradas automáticamente pelo IDE já nos ajudem bastante, o Delphi nos proporciona a possibilidade de customizar de uma forma muito simples, o conteúdo e até mesmo o designer do popup exibido.

Com isso podemos adicionar mais detalhes, e criar uma espécie de “documentação” de nossos identificadores. Para isso, devemos adicionar comentários com uma formatação especial ao nosso código fonte.

Esses comentários devem estar imediatamente acima do identificador, e devem começar com /// (três barras) seguido por uma tag XML reconhecida pelo Help Insight viewer, como no exemplo a seguir:

///<summary> Em resumo este método faz... </summary>

* Note que o texto adicionado na TAG <summary> é exibido no popup menu do Help Insight

EXEMPLO UTILIZANDO DIVERSAS TAGS ACEITAS:

    ///<summary> Adiciona um resumo ... </summary>
    ///<param name="AValor1"> Primeiro parâmetro do tipo <see cref="Double"/> para ... </param>
    ///<param name="AValor2"> Segundo parâmetro do tipo <see cref="Double"/> para ... </param>
    ///<returns> O retorno será ... </returns>
    ///<permission cref="PermissionType"> Este método é permitido a ... </permission>
    ///<remarks>
    ///  Observações: Forma de usar o código:
    ///  <code>
    ///    <para> LResult := THelpInsightUtils.MultiplicarValores(10 + 20.5); </para>
    ///    <para> ShowMessage(LResult.ToString); </para>
    ///  </code>
    ///</remarks>
    ///<comments> <para> Caso seja necessário, pode ser adicionado comentários. </para>
    ///  <para> Outras tags aceitas: </para>
    ///  <para> p ou P: parágrafo </para>
    ///  <para> b ou B: <b> Negrito </b> </para>
    ///  <para> i ou I: <i> Itálico </i> </para>
    ///  <para> ------------------------------------------- </para>
    ///  <para> Texto em fonte normal: </para>
    ///  <para> III </para>
    ///  <para> WWW </para>
    ///  <para> <c>Texto em fonte de largura fixa:</c> </para>
    ///  <para> <c>III</c> </para>
    ///  <para> <c>WWW</c> </para>
    ///</comments>
    ///<comments> <para> Este é a comentário 2 e será agrupada ao comentário 1. </para></comments>
    ///<exception cref="ArgumentNullException">
    ///  Se os parâmetros <c>AValor1</c> ou <c>AValor2</c> for um número negativo, uma exceção será gerada.
    ///</exception>

📄 TAGS XMLS QUE PODEM SER UTILIZADAS

///<summary>Adicinar_um_resumo</summary>

///<param name="nome-do-parametro"> Informar os parâmetros do método <see cref="Double"/>. </param>

///<returns> Informar dados do retorno </returns>

///<permission cref="PermissionType"> Dados sobre permissões ... </permission>

///<remarks> Adicionar observações ... </remarks>

///<code> Adicionar exemplos de códigos fontes de como usar </code>

///<comments> Adicionar comentários sobre ... </comments>

///<exception cref="ArgumentNullException"> Informações sobre exceções. Ex.: se o parâmetro não for informado... </exception>

<para> Adiciona um parágrafo </para>

<p> Adiciona um parágrafo </p>

<b> Texto em negrito </b>

<i> Texto em itálico </i>

<i> Texto em itálico </i>

<c> Texto com fonte de largura fixa (Courier New) </c>

Referência a um tipo, símbolo ou identificador específico:

<see cref="string"/>

ONDE O HELP INSIGHT PODE SER USADO?

Help Insight podem ser utilizados em:

✔️ Classes
✔️ Procedures
✔️ Functions
✔️ Constantes
✔️ Enumerados
✔️ Variáveis de instância (declaradas no escopo private, protected, public ou published das classes)
❌ Variáveis locais NÃO SÃO SUPORTADAS pelo Help Insight

🎨 ALTERANDO OS DADOS E LAYOUT DO POPUP

Além de utilizarmos as TAGs disponibilizadas e demonstradas neste artigo, podemos também alterar ou adicionar nossas próprias TAGs XML, assim como alterar o Layout do popup exibido.

Para isso basta editar os arquivos HelpInsight.xsl e HelpInsight.css (HelpInsight_Dark.css para quem usa o tema dark do IDE) que ficam na subpasta ObjRepos do diretório de instalação do RAD Studio.

Para mim C:\Program Files (x86)\Embarcadero\Studio\20.0\ObjRepos\ uma vez dentro deste diretório devemos acessar a subpasta de idioma, no meu caso “en” para Inglês. Para mim o caminho completo para acessar os arquivos são:

C:\Program Files (x86)\Embarcadero\Studio\20.0\ObjRepos\en\HelpInsight.xsl
C:\Program Files (x86)\Embarcadero\Studio\20.0\ObjRepos\en\HelpInsight.css
C:\Program Files (x86)\Embarcadero\Studio\20.0\ObjRepos\en\HelpInsight_Dark.css

Veja um exemplo de como podemos alterar a estrutura e o layout do popup do Help Insight:

🔗LINKS ÚTEIS

• Help Insight (docwiki embarcadero)
• XML Documentation Comments (docwiki embarcadero)

Não esqueça de deixar seu comentário com dúvidas, dicas ou sugestões.

Grande abraço, e até o próximo post!