O Código é a Verdade, mas a Documentação é o Mapa

Em projetos corporativos complexos, a “documentação” costuma ser o primeiro artefato a morrer. No entanto, no ecossistema do Delphi 13, a manutenibilidade é crítica. Quando falamos de sistemas com milhões de linhas de código, o custo de um desenvolvedor novo entender uma Unit complexa é altíssimo.

Neste artigo, vamos implementar um workflow moderno de Documentation-as-Code. Vamos sair do comentário manual e utilizar IA para gerar documentação técnica compatível com o LSP (Language Server Protocol) do Delphi e diagramas arquiteturais vivos para seus repositórios Git.

XML Documentation: Muito Além do Comentário

O Delphi utiliza um padrão específico de XML Documentation (os três slashes ///) que é interpretado pelo compilador e pelo Help Insight. Diferente de comentários de bloco ({...}), o XML Documentation é estruturado e acessível via Reflection (RTTI) em certos contextos e exibido flutuante na IDE.

Para um código de nível avançado, não basta dizer “o que” o método faz. Precisamos definir Contratos.

Exemplo Prático: Um Serviço de Cálculo Fiscal

Vamos imaginar uma classe que utiliza Generics e tratamento de exceções específico.

Código Sem Documentação (O que vemos no dia a dia):

type
  TCalculadoraFiscal<T: class> = class
  public
    function CalcularImposto(const Entidade: T; Aliquota: Currency): Currency;
  end;

O Padrão de Excelência (Target): Para que o Code Insight ajude o desenvolvedor, precisamos detalhar as tags <summary>, <param>, <returns>, <exception> e <remarks>.

Snippet de código

type
  TCalculadoraFiscal<T: class> = class
  public
    /// <summary>
    ///   Calcula o imposto incidente sobre uma entidade fiscal genérica.
    /// </summary>
    /// <param name="Entidade">
    ///   Objeto genérico contendo os dados base para tributação (ex: TNotaFiscal, TItemVenda).
    ///   Deve possuir a interface <c>ITributavel</c> implementada.
    /// </param>
    /// <param name="Aliquota">
    ///   Percentual da alíquota a ser aplicada (ex: 18.5 para 18,5%).
    /// </param>
    /// <returns>
    ///   Retorna o valor calculado do imposto, arredondado para 2 casas decimais conforme norma ABNT.
    /// </returns>
    /// <exception cref="EArgumentException">
    ///   Lançada caso a Alíquota seja negativa ou a Entidade seja nil.
    /// </exception>
    /// <remarks>
    ///   Este método utiliza o padrão <b>Strategy</b> internamente para selecionar a regra de arredondamento.
    /// </remarks>
    function CalcularImposto(const Entidade: T; Aliquota: Currency): Currency;
  end;

Nota Técnica: Ao usar <c>ITributavel</c> e <b>Strategy</b>, o Help Insight do Delphi renderiza isso com formatação visual, facilitando a leitura rápida.

A Estratégia de IA: “Unit Parser” com Contexto

Escrever o XML acima manualmente para 50 classes é inviável. A solução é utilizar um LLM (GPT-4o, Claude 3.5 Sonnet) como um Parser Semântico.

O segredo aqui não é pedir “comente esse código”, mas sim pedir para “gerar a especificação XML Documentation baseada na inferência de lógica”.

O Prompt de Engenharia (Copie e Cole)

“Atue como um Engenheiro de Software Sênior especialista em Delphi/Object Pascal. Analise o código fornecido abaixo. Sua tarefa é adicionar o XML Documentation (///) para todas as interfaces, classes, métodos públicos e propriedades publicadas.

Diretrizes Técnicas:

1. Tag Summary: Descreva o propósito de negócio, não a sintaxe. (Ruim: ‘Cria o objeto’. Bom: ‘Inicializa o contexto de conexão com o banco Redis’).
2. Tag Param: Para parâmetros do tipo TDateTime, Currency ou Objetos, especifique o formato ou estado esperado.
3. Tag Exception: Analise o corpo do método. Se houver raise, documente a exceção na interface.
4. Generics: Se houver genéricos <T>, explique a constraint esperada.
5. Output: Retorne apenas o código Delphi completo com os comentários inseridos.”

Resultado Esperado: Ao passar sua Unit crua, a IA devolverá o código pronto para ser colado na IDE, ativando instantaneamente o suporte de documentação para toda a equipe.

Do Código Pascal ao Diagrama Mermaid

Para documentação de arquitetura (nível macro), ler código é lento. Diagramas UML são o padrão, mas mantê-los no Visio/Enterprise Architect é trabalhoso e eles desatualizam rápido.

A solução é usar Mermaid.js, que permite escrever diagramas usando texto (Markdown). Podemos pedir para a IA ler nossa Unit Delphi e gerar o código Mermaid correspondente.

Cenário: Padrão Factory em Delphi

Imagine que temos a seguinte estrutura na unit uPagamentos.pas:

type
  IPagamento = interface
    ['{...}']
    procedure Processar(Valor: Currency);
  end;

  TPagamentoPix = class(TInterfacedObject, IPagamento)
  public
    procedure Processar(Valor: Currency);
  end;

  TPagamentoFactory = class
  public
    class function Criar(Tipo: String): IPagamento;
  end;

Prompt para Geração do Diagrama

“Analise o código Delphi/Pascal acima. Crie um diagrama de classes utilizando a sintaxe Mermaid.js. Mapeie corretamente:

• Interfaces do Delphi para <<interface>>.
• Herança de TInterfacedObject e implementação de interfaces.
• Dependências (quem cria quem).”

Resultado Gerado (Código Mermaid)

classDiagram
    class IPagamento {
        <<interface>>
        +Processar(Valor: Currency)
    }

    class TPagamentoPix {
        +Processar(Valor: Currency)
    }

    class TPagamentoFactory {
        +Criar(Tipo: String) IPagamento
    }

    class TInterfacedObject {
        <<VCL Class>>
    }

    %% Relacionamentos
    TPagamentoPix --|> TInterfacedObject : Inherits
    TPagamentoPix ..|> IPagamento : Implements
    TPagamentoFactory ..> IPagamento : Creates
    TPagamentoFactory ..> TPagamentoPix : Instantiates

Ao colocar este bloco dentro do seu arquivo README.md no GitHub/GitLab, ele será renderizado visualmente, mostrando a arquitetura de dependência da sua Unit sem que você tenha desenhado uma única linha.

Configuração do Compilador no Delphi 13

Para que todo esse esforço gere artefatos físicos (arquivos .xml que podem ser consumidos por geradores de documentação externa como Sandcastle ou DocFX), você deve configurar o projeto:

1. Acesse Project > Options.
2. Navegue até Building > Delphi Compiler > Compiling.
3. Na seção Output formatting, marque: Generate XML documentation.
4. (Opcional) Em Output directory, defina onde os XMLs serão salvos (geralmente na pasta .\Docs ou junto com o binário).

Dica Avançada: O compilador do Delphi valida a sintaxe do XML. Se você abrir uma tag <summary> e não fechar, receberá um Warning no Build. Isso garante a integridade da sua documentação técnica.

Conclusão

A manutenibilidade no Delphi moderno não é sobre escrever textos longos em Word, mas sobre manter a documentação próxima ao código (Co-location).

Utilizando IA para gerar o XML Documentation, você ganha produtividade e garante que o IntelliSense da IDE seja útil. Utilizando IA para converter Pascal em Mermaid, você garante que seu README.md explique a arquitetura visualmente.

Sugestão de Ação: Pegue a Unit mais complexa e “obscura” do seu sistema hoje. Passe-a por um LLM com o prompt de “Unit Parser” sugerido acima e veja a diferença na clareza do código imediatamente.