The Wiert Corner – irregular stream of stuff

Jeroen W. Pluimers on .NET, C#, Delphi, databases, and personal interests

  • My badges

  • Twitter Updates

  • My Flickr Stream

  • Pages

  • All categories

  • Enter your email address to subscribe to this blog and receive notifications of new posts by email.

    Join 2,482 other followers

XMLDoc Delphi source code documentation generation – some links

Posted by jpluimers on 2021/06/23

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:

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:

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:

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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

 
%d bloggers like this: