Recentemente li um artigo sobre
Help Insight que chamou bastante minha atenção.
Acredito que todos saibam o que é ou já tiveram contato com essa funcionalidade, mas para aqueles que não estão acostumado com o nome
Help Insight, esse é um recurso do IDE do Delphi que apresenta um popup com uma breve descrição sobre o identificador (classe, método, função, variável, ...) na qual o cursor do mouse está posicionado.
Também é possível invocar o Help Insight através do pressionamento das teclas
CTRL + SHIFT + H.
Por padrão é apresentado nesse popup menu as seguintes informações:
- Nome do identificador
- Categoria do identificador (Campo, variável, método, classe, propriedade, ...)
- Localização (nome da unit seguido pelo número da linha e da coluna)
- Tipo (Se o identificador é string, integer, ...)
No caso do identificador ser um método, function ou procedure, a descrição é extendida apresentando também o(s) parâmetro(s) e o valor de retorno.
Isso tudo é feito automaticamente pelo IDE em tempo de edição, ou seja, nem necessitar que o código seja compilado.
O que eu não sabia, e é o objetivo desse artigo, é que o conteúdo do popup menu pode ser customizado exibindo informações mais detalhadas a respeito do identificador em questão.
Essa customização deve estar situada imediatamente acima do identificador a qual se deseja trabalhar e tem seu início demarcado através de um comentário
coringa (///, três barras) seguido por uma tag XML reconhecida pelo Help Insight viewer.
As tags XML atualmente reconhecida são:
- summary
- param
- returns
- permission
- remarks
- comments
Agora vamos ver um exemplo prático contendo todas essas tags.
/// <summary> Verificar se um determinado componente/field teve ou não seu conteúdo
/// alterado. O método é utilizado dentro do framework para sinalizar os
/// componentes que foram modificados durante uma operação de update.</summary>
/// <param name="FieldComp"> Registro contendo informações sobre o field/componente. </param>
/// <param name="Index"> Índice do registro dentro da lista (<c>FFieldList</c>). </param>
/// <param name="Modified"> Parâmetro de saída que deve ser setado para True/False, dependendo
/// do status verificado pelo método. Por padrão, o parâmetro vem
/// com o valor True. </param>
/// <returns> O valor retornado deve significar que o método obteve sucesso ao comparar o
/// valor original com o valor atual do componente/field, ou seja, que o valor
/// do parâmetro Modified é válido.</returns>
/// <permission> Esse método é utilizado internamente apenas quando o formulário está em estado
/// de alteração de registro. A implementação original trás suporte para os
/// componentes mais comumente utilizados, entretanto, em caso de customização ou
/// extenção do suporte a outros componentes, esse método pode sempre ser
/// reimplementado nos formulários filhos. </permission>
/// <remarks> Originalmente esse método foi concebido para ser utilizado pelo framework como
/// um serviço. Assim, evite chamá-lo diretamente a menos que saiba com exatidão
/// o que está fazendo. </remarks>
/// <comments> Caso necessite reimplementar o método, é recomendado que faça uma chamada à
/// implementação da classe pai (Exemplo: Result := inherited;). </comments>
Observe que foi utilizado também as tags
<c> e </c>. Essas tags delimitam um área de texto que será formatada no estilo de código fonte do Delphi (por padrão, Courier New).
O resultado é:
Convenhamos que se você está navegando pelo código, um help assim é muito, mas muito mais útil do que simplesmente visualizar a assinatura do identificador (padrão do Delphi), certo? Além do mais, você não precisa se deslocar até a definição/implementação/declaração do identificador para obter maiores detalhes, o que quase sempre resulta na interrupção da linha de raciocínio durante alguma investigação.
Uma outra vantagem que notei sobre a utilização do Help Insigh é poder ter dois tipos de
documentação a respeito de um método sobre dois pontos de vista.
Deixa eu exemplificar. Observe o código fonte abaixo.
unit Unit1;
interface
uses
Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
Dialogs;
type
TForm1 = class(TForm)
private
{ Private declarations }
protected
function FieldIsModified(var FieldComp: TFieldItem; const Index: Integer; out Modified: Boolean): Boolean; virtual;
public
end;
var
Form1: TForm1;
implementation
{$R *.dfm}
{ TForm1 }
{_/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\
Definition.: Protected Strict [ ] Virtual/Override [X] Event [ ]
Ojective...:
Usefulness.:
Parameters.: [ I ] FieldComp =
[ I ] Index =
[ O ] Modified =
Result.....:
Comments...:
_/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\__/-\}
function TForm1.FieldIsModified(var FieldComp: TFieldItem; const Index: Integer; out Modified: Boolean): Boolean;
begin
// ...
end;
end.
Creio que a prática mais comum de documentação de código seja a inclusão de comentários imediatamente acima da implementação dos métodos/funções (como apresentando no exemplo acima), ficando a área de interface da unit com apenas as definições.
O código fonte acima contém a estrutura do bloco de comentário que costumo utilizar para documentar um método ou uma function (removi o texto para ficar mais fácil sua visualização). As informações que acrescento nesse bloco estão relacionadas principalmente com seu funcionamento, com sua dependência perante a solução como um todo e com cuidados que devem ser tomados na sua utilização.
Quando penso no Help Inside, penso em um ponto de vista onde saber como é o funcionamento interno de um método não é tão importante, naquele momento, quanto saber o que o método faz, suas entradas e suas saídas. Assim, quando digo que o Help Insight proporciona um segundo tipo de comentários é justamente a possibilidade de documentar o código fonte sob uma perspectiva mais focada no
conceito do que em detalhes intrínsecos ao funcionamento.
Apesar de muito útil, fique um tanto desconfortável com relação a legibilidade (ou melhor, à falta de legibilidade) que a estrutura de definição das tags causa ao layout da classe.
Por exemplo, se você possui um classe com vários métodos e propriedades. Acrescentar um help insigh para cada definição irá dinimuir a visão do todo por exigir constante deslocamento entre as linhas para navegar pela classe (aqui o
layout struct do Delphi se mostrou ainda mais útil).
Fiz alguns testes e notei que o IDE aceita a utilização de REGIONS para delimitar a área do Help Insight, o que pareceu uma forma bem razoável para resolver ou, no mínimo, minimizar a área visível ocupada.
Um segundo ponto com relação a legibilidade é que não há uma formatação específica para as tags.
a) É possível escrever a descrição de uma tag utilizando multi-linhas ou em apenas uma única linha que o conteúdo será apresentado igualmente no popup;
b) Pode-se acrescentar espaços vários espaços em brancos, mas os excedentes serão ignorados (assim como em HTML);
c) Qualquer quebra de linha será ignorada, o que dá margem para formatar melhor o texto na unit, mas na hora de exibir o popup, as frases serão concatenadas em um único parágrafo.
Isso faz com que não seja possível escrever um pequeno trecho de código, por exemplo.
Em outras palavras, fiquei com a impressão que é mais legível ler as descrições do popup do que diretamente do código fonte.
Caso deseje analisar o código fonte completo da unit criada durante a escrita desse artigo, faça o download nesse link.
A última dica é para aqueles de desejam alterar a saída do popup para um layout mais adequado ou apenas queiram fazer pequenos incrementos. Nesse caso basta editar o arquivo HelpInsight.xsl (sub-diretório
ObjRepos do diretório de instalação do RAD Studio, para mim é
C:\Program Files\Embarcadero\RAD Studio\7.0\ObjRepos). Lá você encontrará também outras opções não descrita nesse artigo.
Boa sorte.
