XMLDoc Delphi source code documentation generation – some links

There is very little information on how to use the XMLDoc documentation formatting in your Delphi source code.

So here are some links for me to get started:

• [WayBack] XMLDoc Delphi source code documentation generation – Stack Overflow (which in one question, asks both about standards and tooling).
• [WayBack] delphi – IDE Plugin for XMLDoc – Stack Overflow which mentions [WayBack] Documentation Insight by [WayBack] DevJet Software, a tool I like very much.
• [WayBack] Code documentation for delphi similar to javadoc or c# xml doc – Stack Overflow talks a bit about tooling.
• WayBack: Documenting Delphi – Stack Overflow (since the StackOverflow moderators think useful information should be deleted).

XmlDoc comments can get verbose because of the lengthy XML syntax.

Hiding them in regions can help, for instance with the plugin at [WayBack] Fast-Forward »: XML Documentation in Delphi 2006.

I still should try NDoc – Wikipedia for post processing of the Delphi generated XML file, but since I almost exclusively use the internal IDE viewer, that is good enough for me now.

Syntax

Most of the above links talk about tooling, but little about syntax. Luckily, it is very similar to the C# XML Documentation syntax documented by Microsoft:

• [WayBack] XML Documentation Comments – C# Programming Guide | Microsoft Docs
• [WayBack] Recommended Tags for Documentation Comments – C# Programming Guide | Microsoft Docs
• [WayBack] Delimiters for Documentation Tags – C# Programming Guide | Microsoft Docs
• [WayBack] How to: Use the XML documentation features – C# Programming Guide | Microsoft Docs

DevJet has a nice document describing all Delphi supported tags in [WayBack] Delphi-Documentation-Guidelines.pdf (via [WayBack] DevJet Software » Delphi Documentation Guidelines) including the tags mentioned in [WayBack] Dr.Bob Examines… #100: Generating Documentation.

For comparison:

• [WayBack] XML Documentation Comments – RAD Studio
• [WayBack] Delphi 2007: Compiler:
  

  Generate XML documentation

  Processes documentation comments in the code and creates an XML file named ProjectDoc.xml in the same directory as the project file (.csproj for MSBuild format). Lines beginning with /// and preceding a user-defined type such as a class, delegate, or interface; a member such as a field, event, property, or method; or a namespace declaration can be processed as comments and placed in the file. Corresponds to /doc.

• [WayBack] Error Messages:
  • [WayBack] W1201: XML comment on ‘%s’ has badly formed XML–‘Whitespace is not allowed at this location.’
  • [WayBack] W1202: XML comment on ‘%s’ has badly formed XML–‘Reference to undefined entity ‘%s”
  • [WayBack] W1203: XML comment on ‘%s’ has badly formed XML–‘A name was started with an invalid character.’
  • [WayBack] W1204: XML comment on ‘%s’ has badly formed XML–‘A name contained an invalid character.’
  • [WayBack] W1205: XML comment on ‘%s’ has badly formed XML–‘The character ‘%c’ was expected.’
  • [WayBack] W1206: XML comment on ‘%s’ has cref attribute ‘%s’ that could not be resolved (directing to [WayBack] <see> (C# Programming Guide))
  • [WayBack] W1207: XML comment on ‘%s’ has a param tag for ‘%s’, but there is no parameter by that name
  • [WayBack] W1208: Parameter ‘%s’ has no matching param tag in the XML comment for ‘%s’ (but other parameters do)
• [WayBack] Code Editor:
  

  Help Insight

  Help Insight displays a hint containing information about the symbol such as type, file, line # declared at, and any XML documentation associated with the symbol (if available).

  Invoke Help Insight by hovering the mouse over an identifier in your code, while working in the Code Editor. You can also invoke Help Insight by pressing CTRL+SHIFT+H.

One Delphi specific thing on the see tag.

The see tag accepted a syntax like UnitName|IdentifierName (see for instance [WayBack] How/under which circumstances does the tag in Delphi xml comments actually work? – Stack Overflow).

In Delphi 10.1 Berlin, sometimes that did not work and I had to use the UnitName.IdentifierName syntax.

The difference is how it is displayed: UnitName|IdentifierName shows as IdentifierName, whereas UnitName.IdentifierName is shown in full.

Sometimes one or the other is unclickable.

In the Delphi IDE, href references do not work

Similar to C# and the Visual Studio IDE, any href reference will not work in the IDE itself. See [WayBack] C# XML Documentation Website Link – Stack Overflow.

In Delphi, the same para element for paragraphs is used as in C#

Documented in the DevJet documentation, the para element works for paragraphs just like it does in the C# example at [WayBack] How to add a line break in C# .NET documentation – Stack Overflow.

Example

A few important tags:

   TParentedTest = class;
   IParentedTest = ISmartPointer<TParentedTest>;
   /// <summary>
   /// <para><see cref="Data.DataRecord|TJoinableDataRecord" /> that can be parented.</para>
   /// <para>The first time you obtain <see cref="UnitTest.Query.JoinHelper|TParentedTest.Parent" />, it will create one for you (so be careful not to recursively call <c>Parent</c>).</para>
   /// </summary>
   TParentedTest = class(TTest)
   strict private
     /// <summary>
     /// <para>Backing field of <see cref="UnitTest.Query.JoinHelper|TParentedTest.Parent" />.</para>
     /// <para>Referenced by <c>interface</c> <see cref="System|IInterface" /> instead of <c>class</c> <see cref="UnitTest.Query.JoinHelper|TParentedTest.Parent" /> as that prevents use-after-free access violations.</para>
     /// </summary>
     FParentInterface: IInterface;
   public
     class function CreateI(const Name: string): IParentedTest;
     /// <summary>
     /// <para>Ensures there is a parent by creating a new <see cref="UnitTest.Query.JoinHelper|TParentedTest" /> if there is none yet.that can be parented.</para>
     /// <para>Do not call recursively, as it will keep creating parents in an endless loop.</para>
     /// </summary>
     function Parent: TParentedTest;
     destructor Destroy; override;
   end;

–jeroen