Doc Comments
Developmentdoc-commentsDoc Comments is an Agent Skill for development published in the MichaelGrafnetter/DSInternals repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Ensure that C# and C++/CLI types are documented with XML comments and follow best practices for documentation.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/MichaelGrafnetter/DSInternals/blob/HEAD/.agents/skills/doc-comments/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/doc-comments, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
C# and C++/CLI Documentation Best Practices
- All public members in the entire solution should be documented with XML comments.
- It is encouraged to document internal members as well, especially if they are complex or not self-explanatory.
Guidance for all APIs
- Use
<summary>to provide a brief, one sentence, description of what the type or member does. Start the summary with a present-tense, third-person verb. - Use
<remarks>for additional information, which can include implementation details, usage notes, or any other relevant context. - Use
<see langword>for language-specific keywords likenull,true,false,int,bool, etc. - Use
<c>for inline code snippets. - Use
<example>for usage examples on how to use the member.- Use
<code>for code blocks.<code>tags should be placed within an<example>tag. Add the language of the code example using thelanguageattribute, for example,<code language="csharp">.
- Use
- Use
<see cref>to reference other types or members inline (in a sentence). - Use
<seealso>for standalone (not in a sentence) references to other types or members in the "See also" section of the online docs. - Use
<inheritdoc/>to inherit documentation from base classes or interfaces.- Unless there is major behavior change, in which case you should document the differences.
Methods
- Use
<param>to describe method parameters.- The description should be a noun phrase that doesn't specify the data type.
- Begin with an introductory article.
- If the parameter is a flag enum, start the description with "A bitwise combination of the enumeration values that specifies...".
- If the parameter is a non-flag enum, start the description with "One of the enumeration values that specifies...".
- If the parameter is a Boolean, the wording should be of the form "
<see langword="true" />to ...; otherwise,<see langword="false" />.". - If the parameter is an "out" parameter, the wording should be of the form "When this method returns, contains .... This parameter is treated as uninitialized.".
- Use
<paramref>to reference parameter names in documentation. - Use
<typeparam>to describe type parameters in generic types or methods. - Use
<typeparamref>to reference type parameters in documentation. - Use
<returns>to describe what the method returns.- The description should be a noun phrase that doesn't specify the data type.
- Begin with an introductory article.
- If the return type is Boolean, the wording should be of the form "
<see langword="true" />if ...; otherwise,<see langword="false" />.".
Constructors
- The summary wording should be "Initializes a new instance of the class [or struct].".
Properties
- The
<summary>should start with:- "Gets or sets..." for a read-write property.
- "Gets..." for a read-only property.
- "Gets [or sets] a value that indicates whether..." for properties that return a Boolean value.
- Use
<value>to describe the value of the property.- The description should be a noun phrase that doesn't specify the data type.
- If the property has a default value, add it in a separate sentence, for example, "The default is
<see langword="false" />". - If the value type is Boolean, the wording should be of the form "
<see langword="true" />if ...; otherwise,<see langword="false" />. The default is ...".
Exceptions
- Use
<exception cref>to document exceptions thrown by constructors, properties, indexers, methods, operators, and events. - Document all exceptions thrown directly by the member.
- For exceptions thrown by nested members, document only the exceptions users are most likely to encounter.
- The description of the exception describes the condition under which it's thrown.
- Omit "Thrown if ..." or "If ..." at the beginning of the sentence. Just state the condition directly, for example "An error occurred when accessing a Message Queuing API."
C++/CLI Specific Guidelines
C++/CLI uses the same XML documentation syntax as C#, with minor differences:
- Use triple-slash (
///) comments before declarations. - In C++/CLI, XML doc comments must appear immediately before the declaration (no blank lines between the comment and the code).
- Use
<summary>,<param>,<returns>,<remarks>,<exception>, and other tags exactly as in C#. - For managed types (ref class, value class), document the same way as C# classes and structs.
- For native types exposed to managed code, ensure XML comments are added to the managed wrappers.
- Use
<see cref="ClassName::MemberName" />syntax for cross-references in C++/CLI (note the::scope resolution operator). - When documenting interop code, include
<remarks>explaining any native/managed boundary considerations.