30

I have a piece of code that needs some serious documenting and wanted to ask whether a feature similar to C#/.NET's In-code XML-Documentation is available for Embarcadero Delphi. My aim is to display some sort of information on how to use a specific method correctly in the manner that it'd be highlighted in the Autocompletion in Delphi XE3.

Something like this (C#):

/// <summary>
/// Some useful information helping other developers use this method correctly
/// </summary>
public static void ADocumentedMethod();

Does Delphi XE3 support something like this?

Thank you for reading.

FLClover
  • 524
  • 5
  • 13
  • Which distribution of Delphi XE3 do you have ? Could you include this information into your question, please ? – TLama Mar 12 '13 at 12:50
  • 2
    @TLama shouldn't really matter, AFAIK the /// XML-doc is available since D2010, all SKUs, althought it seems to be bit buggy... – ain Mar 12 '13 at 12:52
  • 2
    @ain, I'm talking about [`Documentation Insight`](http://edn.embarcadero.com/cs/article/41911) where, as far as I remember, were quite big restrictions in cheaper distributions of Delphi, weren't they ? – TLama Mar 12 '13 at 12:57
  • It works in Delphi 2009, too. – Andreas Rejbrand Mar 12 '13 at 22:55

1 Answers1

41

The feature is named XML Documentation Comments and is documented here. It appears to have been modelled closely on the equivalent .net feature so you should be right at home with it.

The documentation contains this example:

/// <summary> Removes the specified item from the collection
/// </summary>
/// <param name="Item">The item to remove
/// </param>
/// <param name="Collection">The group containing the item
/// </param>
/// <remarks>
/// If parameter "Item" is null, an exception is raised.
/// <see cref="EArgumentNilException"/>
/// </remarks>
/// <returns>True if the specified item is successfully removed;
/// otherwise False is returned.
/// </returns>
function RemoveItem(Item: Pointer; Collection: Pointer): Boolean;
begin
  // Non-XML DOC comment
  // ...
end;

which results in this help insight hint:

enter image description here

And there are various other ways to process and consume the documentation.

David Heffernan
  • 601,492
  • 42
  • 1,072
  • 1,490
  • 1
    This is perfect! Thank you very much! I feel a bit stupid for not having found this though Googling. – FLClover Mar 12 '13 at 13:04
  • 2
    Also this XML documentation should be present in `interface` section of an unit in order to be displayed in external units. – Paul Oct 10 '17 at 09:50
  • Note, you can also use for Exceptions. Problem is, the exception name (cref) is not shown in the insight hint. (10.3 Rio). – Toon Krijthe May 27 '19 at 09:46
  • Adding to Paul's comment, the link in context https://stackoverflow.com/questions/45995827/delphi-helpinsight-with-summary-in-implementation So, its similar to a line of procedure or function that gets repeated in the interface, implementation. – user30478 Feb 17 '23 at 09:23