Procedure/Function Commenting..

[Ian Branch 121]

Hi Team,

Like most of us I have my own local pattern procedure/function library.

I have been commenting them like this:

Quote

/// <summary>
/// Determines whether any of the specified bits are set in a given bitmask.
/// </summary>
/// <param name="bits">The bitmask to check.</param>
/// <param name="positions">An array of bit positions to check.</param>
/// <returns>True if any of the specified bits are set, False otherwise.</returns>
/// <remarks>
/// - Validates inputs to ensure meaningful results.
/// - Efficiently iterates through positions using a for loop.
/// - Uses bitwise AND and left-shift operations to check individual bits.
/// - Exits early if a matching bit is found, optimizing performance.
/// </remarks>

What this gives me then is a dropdown when I hover over the procedure/finction in my code that looks something like this:

All very handy and a useful reminder of the procedure/function definition.

I forget where I got this from.   😞

Can somebody point me to where this style of documentation/technique is documented please?

 

Regards & TIA,

Ian

[Dalija Prasnikar 1341]

20 minutes ago, Ian Branch said:

Can somebody point me to where this style of documentation/technique is documented please?

https://docwiki.embarcadero.com/RADStudio/Athens/en/XML_Documentation_Comments

 

There are also tools that can help in writing those, so you don't have to do that manually, like https://devjetsoftware.com/products/documentation-insight/

[Ian Branch 121]

Excellent!  Thanks Dalija.

 

Regards,

Ian

 

[Ian Branch 121]

11 minutes ago, Dalija Prasnikar said:

There are also tools that can help in writing those, so you don't have to do that manually, like https://devjetsoftware.com/products/documentation-insight/

They don't appear to have a D12 version yet.  😞

[Uwe Raabe 1889]

There are also some code templates in Delphi to simplify writing these comments: summary, params, returns, remarks

 

[PeterBelow 218]

It might be worth noting that XML documentation tags also work inside a normal Delphi comment (enclosed in braces {}) instead of these horrible triple slash comments copied from C# along with the XML tags themselves. Much easier to maintain in my opinion if a tag content spans several lines.

[dummzeuch 1392]

20 minutes ago, PeterBelow said:

It might be worth noting that XML documentation tags also work inside a normal Delphi comment (enclosed in braces {}) instead of these horrible triple slash comments copied from C# along with the XML tags themselves. Much easier to maintain in my opinion if a tag content spans several lines.

If only the triple slash was the only horrible thing about it. Whoever came up with using XML tags when there was already a working solution with a lot less noise like PasDoc? (based on JavaDoc). Especially since XML in many other areas has already been superseeded with methods that also produce less noise, e.g. JSON.