Hands-on: create or improve software documentation with an AI tool

In this blog post, we aim to enhance — or create from scratch — source code comments for a Delphi/Object Pascal component using GitHub Copilot Free and JetBrains AI Assistant. The IntelliJ Community Edition, equipped with the provided plugins, serves as our development environment. However, since we’re focusing solely on comment blocks, the choice of IDE is not particularly critical.

As we will use Doxygen for the generation of HTML documents from the component’s source code, the generated comments must follow the Doxygen specification for special comment blocks.

---

Prompt #1: Add missing doxygen comments for enumerations

The Challenge — or: What Are We Trying to Achieve?

During a code review of the component’s codebase, we identified numerous enumeration type declarations with incomplete comments. This issue became especially noticeable after configuring Doxygen to include all enumeration types in the generated HTML documentation.

Our goal is to transform this partially documented type definition (see example below) into a fully documented one. In the improved version, each enumeration value includes a Doxygen comment placed directly after it—for better readability and easier maintenance.

  (**
   * Enum for logging levels.
   *)
  TLogLevel = (logDebug, logInfo, logWarning, logError, logFatal);

The Doxygen comment blocks should follow this structure:

  (**
   * Enum for logging levels.
   *)
  TLogLevel = (logDebug,   //!< Debug-level messages
               logInfo,    //!< Informational messages
               logWarning, //!< Warning messages
               logError,   //!< Error messages
               logFatal    //!< Fatal error messages
              );

Let’s get started and evaluate how effectively the AI plugin assists with this task and how useful the results are. If it proves successful, we can apply it to the many other enumeration types that were overlooked during the software development process.

Steps

Preparation

To help the AI understand the desired documentation style, we start by selecting an enumeration that already has a complete documentation block. Then, we extend the text selection to include the enumerations that don’t yet have any documentation. Whether this preparation is necessary likely depends on the capabilities of the AI tool — or possibly the phase of the moon.

PLUGIN INVOCATION (GitHub Copilot)

We select the source code for the type definition—or a group of them, as mentioned earlier—and use the gutter icon to launch the GitHub Copilot prompt. In the prompt field, we enter: “Add missing Doxygen comments for enumerations.”

---

The generated code appears after some seconds and already looks good enough for our needs.

Hint: The double-arrow button ⇆ in the GitHub Copilot window lets you preview the changes. In the preview area, you can use a button to apply the changes to your code (see below).

Verification

Before finally committing the changes to version control, we run the Doxygen compiler to generate the HTML documentation. Then, we open the documentation and navigate to the enumeration section to review the output and verify that the comments appear as expected.

Did the results meet our needs?

Yes, completing the documentation worked very well for us.

Pro tip: Before executing the AI tool steps, we pulled the complete component code from source control so we could review and test everything before committing. In the IDE, we only had to open the component project folder using File > Open…

---

Prompt #2: Improve selected Doxygen comment blocks

We want to clean up and enhance this type definition for our ‘simple DOM document’ class, TSimpleDomDocument:

  (**
   * A class which represents a document.
   *)
  TSimpleDomDocument = class(TSimpleDomNode, ISimpleDomDocument)
  private
    (** add a paragraph *)
    procedure AddPar;
    function LastParagraph: TParagraphNode;
    function LastText: TTextNode;
  public
    (** create a new instance of the TSimpleDomDocument class *)
    constructor Create;
    (** add a string to the document *)
    procedure Add(const S: string); overload;
    (** add an encoded string to the document *)
    procedure AddEncoded(const S: string);
  end;

This time we want to try a different AI tool. For this example we choose JetBrains AI Assistant.

Plugin invocation (JETBRAINS AI Assistant)

We select the code block and start a new AI chat by clicking “New Chat using Selection” from the selection’s context menu:

In the next step, we enter our prompt “Improve doxygen comment blocks” just above the quoted Pascal code:

---

The suggested changes appear after a couple of seconds.

  (**
   * Creates a new instance of the TSimpleDomDocument class.
   *
   * This constructor initializes a new instance of the TSimpleDomDocument class,
   * and automatically adds an empty starting paragraph to the document.
   *)
  constructor Create;

  (**
   * Adds a string to the document.
   *
   * This method appends the specified string to the current text node
   * in the last paragraph of the document. If the current text node
   * does not exist, a new one will be created automatically.
   *
   * @param S The string to be added to the document.
   *)
  procedure Add(const S: string); overload;

  (**
   * Adds an encoded string to the document.
   *
   * This method appends an encoded version of the specified string to
   * the current text node in the last paragraph of the document. It sets
   * the text node as encoded before adding the string. A new text node
   * is added before and after the encoded string to separate it from
   * other content for better control over formatting.
   *
   * @param S The string to be added in its encoded form.
   *)
  procedure AddEncoded(const S: string);

The Doxygen comments suggested by the AI include accurate implementation details that are actually useful and worth keeping.

We decide to accept the changes and click “Insert Snippet at Caret“:

Verification

We run the Doxygen compiler to generate the HTML documentation. Then, we navigate to the TSimpleDomDocument Class Reference page to review the output and verify that the comments appear as expected.

Did the results meet our needs?

Yes, although the generated descriptions require careful review to catch any inaccuracies caused by the AI’s misinterpretations. Additionally, some method and parameter names would benefit from renaming to better reflect their purpose—an improvement that aids both developers and documentation readers.

---

References

• Doxygen – https://www.doxygen.nl/
• pas2dox – https://sourceforge.net/projects/pas2dox/
• GitHub Copilot Free – https://github.com/features/copilot
• JetBrains AI Assistant – https://www.jetbrains.com/ai-assistant/