Modern C# and .NET Tutorial: Cross-Platform Basics/

...

/

Documenting Function with XML Comments and Lambda Usage

Documenting Function with XML Comments and Lambda Usage

Learn about enhancing tooltip information in C# by adding XML documentation comments and functional-first language.

We'll cover the following...

By default, when calling a function such as CardinalToOrdinal, code editors will show a tooltip with basic information, as shown in the figure:

Press + to interact
A tooltip showing the default simple method signature
A tooltip showing the default simple method signature

Improving tooltip

Let’s improve the tooltip by adding extra information:

Step 1: If you are using Visual Studio Code with the C# extension, navigate to “View | Command Palette | Preferences”: “Open Settings (UI)”, and then search for formatOnType and ensure it is enabled. C# XML documentation comments are a built-in feature of Visual Studio 2022.

Step 2: On the line above the CardinalToOrdinal function, type three forward slashes ///, and note that they are expanded into an XML comment that recognizes that the function has a single parameter named number, as shown in the following code:

Press + to interact
/// <summary>
///
/// </summary>
/// <param name="number"></param>
/// <returns></returns>

Step 3: Enter suitable information for the XML documentation comment for the CardinalToOrdinal function. Add a summary, and describe the input parameter and the return value, as shown highlighted in the following code:

Press + to interact
/// <summary>
/// Pass a 32-bit integer and it will be converted into its ordinal equivalent.
/// </summary>
/// <param name="number"> Number as a cardinal value e.g. 1, 2, 3, and so on.</param>
/// <returns>Number as an ordinal value e.g. 1st, 2nd, 3rd, and so on.</returns>

Step 4: Now, when calling the function, we will see more details, as shown in the figure:

Press + to interact
A tooltip showing the more detailed method signature
A tooltip showing the more detailed method signature

It is worth emphasizing that this feature is primarily designed to be used with a tool that converts the comments into documentation. A secondary feature is the tooltips that appear while entering code or hovering over the function name.

Local functions and XML comments

Local functions do not support XML comments because local functions cannot be used outside the member in which they are declared, so it ...