This is the archived version of Roland Weigelt's weblog that ran from 2003 to 2023 at weblogs.asp.net

Trying out What ChatGPT Knows About XML Doc Comments

Back in 2003, I started a Visual Studio add-in called “GhostDoc” that used some simple heuristics to create basic XML doc comments as a starting point for writing the “real” documentation (remarks on the purpose, edge cases, special parameter values, etc. but not implementation or other internals). GhostDoc did not really understand the English language, but relied on recommended naming conventions of the .NET Framework. Later versions were also able to use documentation of base classes and interfaces.

I worked on GhostDoc until 2009 when SubMain acquired the rights to the software. Since then, the topic of documentation continues to play an important role for me. Some of my hobby projects have a considerable amount of old code that has not been modified for years, and thus is used more like a third-party library. It is not uncommon that I come across a helpful <remark> tag that I added to the auto-generated XML doc comment for an “obvious” function  – wondering whether I would have written the remark back then if I had to write all the boiler text myself.

Trying out ChatGPT

When I got around to playing with ChatGPT, one thing I wondered whether it could write XML doc comments. So here is how that went:

My question to ChatGPT:

In the context of the .NET framework and the C# language, do you know what an XML doc comment is?

ChatGPT’s answer:

Yes, I'm familiar with XML doc comments in the context of .NET framework and C# language. XML doc comments are special comments that are used to document code elements such as classes, methods, properties, events, and parameters in C# code. They are written using XML syntax and provide a way to add documentation directly to the source code, which can be later extracted and used to generate documentation for the code.

XML doc comments begin with three forward slashes (///) in C# and are placed immediately before the code element that is being documented. They can contain various XML tags such as <summary>, <param>, <returns>, <example>, etc., to provide structured documentation for the code element. For example, the <summary> tag can be used to provide a summary of what a code element does, the <param> tag can be used to document parameters of a method, and the <returns> tag can be used to document the return value of a method.

XML doc comments are commonly used by developers to generate API documentation using tools such as Visual Studio's IntelliSense or third-party documentation generators like Sandcastle or DocFX. They can also be used to provide documentation for library users to understand how to use the code correctly and effectively.

Question:

Could you write an XML doc comment for a function with the following signature: public string GetDetailedExceptionMessage(Exception exception)

ChatGPT:

Sure! Here's an example of an XML doc comment for the given function signature:

/// <summary>
/// Gets a detailed exception message that includes the exception message,
/// inner exception message(s), and stack trace information.
/// </summary>
/// <param name="exception">The exception for which to retrieve the detailed message.</param>
/// <returns>
/// A string containing the detailed exception message, including the exception message,
/// inner exception message(s), and stack trace information.
/// </returns>
public string GetDetailedExceptionMessage(Exception exception)
{
// Implementation goes here
}

[… rest of answer omitted for brevity …]

That is pretty impressive.

And no, I do not have plans to write an XML doc generator using ChatGPT…

No Comments