Access to this page requires authorization. You can try signing in or changing directories . Access to this page requires authorization. You can try changing directories . The ultimate goal for .NET API docs is to have the /// XML comments in the .NET source code be the "source of truth". For MSBuild, ASP.NET Core, and EF Core, this goal has been met. However, currently the dotnet-api-docs repo remains the source of truth for some namespaces in the .NET API reference. This dotnet/runtime issue tracks the effort to backport .NET docs and make the dotnet/runtime repo the source of truth. The presence or absence of the "edit" button on a page often indicates that the dotnet-api-docs repository is the source of truth. If it's missing, the source of truth is likely the /// comments in the source repo. This article provides tips about writing good doc comments within the source code itself . Good comments make for good documents .NET API triple-slash comments are transformed into public documentation on learn.microsoft.com and also appear in IntelliSense in the IDE. The comments should be: Complete—empty doc entries for methods, parameters, exceptions, and so on, make the APIs feel under-supported, temporary, or trivial. Correct—readers scan for critical details and become frustrated when key information is missing or incorrect. Contextual—readers land on this page from search and need to know how and when to use the API, and what the code implications are. Polished—poor or hasty grammar and spelling can confuse the reader and make even simple calls ambiguous; also, poor presentation communicates low investment. Use cref instead of href to link to another type or method. Correct: <param name="configFile">An <see cref="XmlConfigResource" /> object.</param> Incorrect: <param name="configFile">An <a href="https://learn.Microsoft.com/{path}/XmlConfigResource"></a> object.</param> Use cref instead of href to link to another type or method. Correct: <param name="configFile">An <see cref="XmlConfigResource" /> object.</param> Incorrect: <param name="configFile">An <a href="https://learn.Microsoft.com/{path}/XmlConfigResource"></a> object.</param> When referencing parameters, wrap the parameter name in a <paramref> tag, for example, The offset in <paramref name="source" /> where the range begins. . When referencing parameters, wrap the parameter name in a <paramref> tag, for example, The offset in <paramref name="source" /> where the range begins. . If you have more than one paragraph in the doc comment, separate the paragraphs with <para> tags. If you have more than one paragraph in the doc comment, separate the paragraphs with <para> tags. Wrap code examples in <code> tags within <example> tags. Wrap code examples in <code> tags within <example> tags. Use <seealso> to add links to other APIs in the autogenerated "See Also" section. Use <seealso> to add links to other APIs in the autogenerated "See Also" section.

For more information, see Recommended XML tags for C# and the C# specification . The ECMAXML spec also has good information, although be aware that there are some differences between ECMAXML and /// documentation comments (for example, cref targets are fully expanded and have prefixes in ECMAXML). Cross references When you use a <see cref> tag to link to another API, there's no need to add a prefix to the type name, such as T: for type or M: for method. In fact, code analysis rule CA1200 flags code comments that add a prefix to the type name in a cref tag. However, there are a couple exceptions to this rule: When you want to link to the general form of a method that has more than one overload, the C# compiler doesn't currently support that . The workaround for docs is to prefix the method name with O: in source code (or Overload: in ECMAXML) and suppress rule CA1200 . For example: <altmember cref="O:System.Diagnostics.Process.Kill" /> . When the API can't be resolved from the current context, which includes any using directives. In this case, use the fully qualified API name with a prefix. When the <see cref> tag is converted to ECMAXML , mdoc replaces the type name with the full DocId of the API, which includes a prefix. For authoritative guidelines about describing each symbol type and its various parts, see the .NET API docs wiki . The well-known placeholder text for empty comments is To be added. . The Learn build system recognizes this text and removes it when the ECMAXML is converted into HTML, leaving an empty description. Separate code files If your code example is lengthy, you can put it in a separate file in the docs repo and link to it from source code in the following way: For some more details about how to hook up separate code files, see this discussion . Language attributes Language attributes on <code> tags are optional, but they cause the code to be formatted with color coding. For example: When documenting an API that's not intended to be used by consumers, use wording similar to the following: <summary>This type supports the .NET infrastructure and is not intended to be used directly from your code.</summary> Recommended XML tags for C# Documentation comments (C# specification) Was this page helpful? Need help with this topic? Want to try using Ask Learn to clarify or guide you through this topic? Additional resources Last updated on 2025-06-17