README

Help Insight Delphi

Alterar idioma

-green) -red)

Contatos

▶️ Vídeo de demonstração

• Acessar 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 precionando as teclas CTRL + SHIFT + H

Veremos neste repositório/artigo criar e personalizar Help Insight para nossas aplicações.

HELP INSIGHT PADRÕ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.

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 \ é 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>

<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)

[!IMPORTANT] ⭐ Não se esqueça de deixar sua estrela para ajudar a propagar o repositório.

Voltar para o Topo