API documentation uses the /** */ comment syntax instead of the XML documentation comment syntax ///.
API documentation should use /// instead of /** */ because /// creates XML comments that the .NET compiler understands.
These comments show up in IntelliSense, help generate external documentation, and follow a structured format.
/** */ is just for general comments and will not be used by tools or IDEs to provide helpful information.
The .NET ecosystem has standardized on XML documentation comments using /// syntax.
This format is recognized by compilers, IDEs, and documentation generation tools.
Using /** */ instead means losing all these benefits.
Using /// instead of /** */ provides several important benefits:
-
IntelliSense Support: Only
///comments appear in IntelliSense tooltips when developers hover over methods or types. Comments using/** */are ignored by IntelliSense, making them invisible to API consumers. -
Documentation Generation: Tools like DocFX, Sandcastle, and others generate external documentation from XML comments. They cannot process
/** */comments, meaning the documentation will not appear in generated docs. -
Compiler Processing: The C# compiler processes
///comments and can generate XML documentation files during compilation. These files are used by IDEs and documentation tools./** */comments are not processed by the compiler. -
Structured Format: XML documentation comments support structured tags like
<summary>,<param>,<returns>, and more. This allows for rich, organized documentation that tools can parse and present effectively. -
Consistency with Ecosystem: The entire .NET ecosystem uses
///for API documentation. Using this standard format ensures code fits naturally into the broader ecosystem. -
Better Tooling: IDEs provide special support for XML documentation comments, including auto-completion for tags, validation, and formatting. This makes writing documentation easier and more reliable.
To fix a violation of this rule, replace /** */ comment blocks with /// XML documentation comments.
Convert the content into appropriate XML tags like <summary>, <param>, and <returns>.
#pragma warning disable MiKo_2239
#pragma warning restore MiKo_2239