-green){kind=icon}
-red){kind=icon}
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 precionando as teclas CTRL + SHIFT + H
Veremos neste repositório/artigo criar e personalizar Help Insight para nossas aplicações.
Por padrão, o IDE do Delphi gera automáticamente 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 automáticamente em tempo de edição, ou seja, sem necessitar que o código seja compilado.
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
/// <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>
///<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>
<c> Texto com fonte de largura fixa (Courier New) </c>
Referência a um tipo, símbolo ou identificador específico:
<see cref="string"/>
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
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:
Important
⭐ Não se esqueça de deixar sua estrela para ajudar a propagar o repositório.