Writing Documentation for a C# Project: From A to Z

Writing Documentation for a C# Project: From A to Z

High-quality documentation is the key to a successful and maintainable C# project. It helps developers quickly understand the code, facilitates onboarding of new team members, and reduces the number of errors. In this article, we will break down the entire process of creating documentation for a C# (.NET) project: from the basics of XML comments to automatically generating beautiful websites.

1. Basics of XML Comments in C#

The standard way to document code in C# is XML comments. They are written before the declaration of a class, method, property, or other element and start with three slashes ///. The C# compiler recognizes these comments and can generate an XML documentation file.

Here are the basic tags you will use most often:

\n
• <summary> — a brief description of the element.
\n
• <param name="name"> — description of a method parameter.
\n
• <returns> — description of the return value.
\n
• <exception cref="Type"> — description of an exception that the method may throw.
\n
• <example> — usage example.
\n
• <remarks> — additional notes.
\n

Example of a correct XML comment for a method:

/// <summary>\n/// Calculates the factorial of a non-negative integer.\n/// </summary>\n/// <param name="n">A non-negative integer.</param>\n/// <returns>The factorial of the number n.</returns>\n/// <exception cref="System.ArgumentException">Thrown if n is less than 0.</exception>\n/// <example>\n/// <code>\n/// int result = Factorial(5);\n/// // result equals 120\n/// </code>\n/// </example>\npublic static int Factorial(int n)\n{\n    if (n < 0)\n        throw new ArgumentException("n cannot be negative", nameof(n));\n\n    int result = 1;\n    for (int i = 1; i <= n; i++)\n    {\n        result *= i;\n    }\n    return result;\n}

2. Documenting Classes and Properties

Don't forget to document not only methods but also the classes themselves, as well as their properties and fields. This is especially important for public APIs that will be used by other developers.

For properties, use the <summary> and <value> tags (for describing the stored value):

/// <summary>\n/// Represents a system user.\n/// </summary>\npublic class User\n{\n    /// <summary>\n    /// Unique user identifier.\n    /// </value>\n    public int Id { get; set; }\n\n    /// <summary>\n    /// Full name of the user.\n    /// </summary>\n    /// <value>A string containing the first and last name.</value>\n    public string FullName { get; set; }\n\n    /// <summary>\n    /// Creates a new user.\n    /// </summary>\n    /// <param name="id">Identifier.</param>\n    /// <param name="fullName">Full name.</param>\n    public User(int id, string fullName)\n    {\n        Id = id;\n        FullName = fullName ?? throw new ArgumentNullException(nameof(fullName));\n    }\n}

3. Generating the XML File and Building Documentation

To get an XML file from your comments, you need to configure the project. In Visual Studio or via the .csproj file, add:

<PropertyGroup>\n  <GenerateDocumentationFile>true</GenerateDocumentationFile>\n  <DocumentationFile>bin\\$(Configuration)\\$(TargetFramework)\\$(AssemblyName).xml</DocumentationFile>\n  <NoWarn>$(NoWarn);1591</NoWarn> <!-- Disables the warning about missing comments if needed -->\n</PropertyGroup>

After building the project, you will get an XML file that can be used to create a beautiful