XML Doc Comments

Context Actions for XML Doc Comments

Embrace with <c>...</c>

Embraces the selected text with the <c> and </c> tags. If no text is selected, the word under the caret is used.

⚠️ Known Limitation

• No checks if the result becomes a valid XML.

Embed into <see cref="..."/>

Embeds the selected text into the href attribute of the <see> tag. If no text is selected, the word under the caret is used.

⚠️ Known Limitations

• No checks if the result becomes a valid XML.
• No checks if the embedded text is a valid identifier, thus, corresponding using statement is not added automatically (use ReSharper suggestions).

Embed into <paramref name="..."/>

Embeds the selected text into the name attribute of the <paramref> tag. If no text is selected, the word under the caret is used.

⚠️ Known Limitations

• No checks if the result becomes a valid XML.
• No checks if the embedded text is a valid parameter.

Embed into <typeparamref name="..."/>

Embeds the selected text into the name attribute of the <typeparamref> tag. If no text is selected, the word under the caret is used.

⚠️ Known Limitations

• No checks if the result becomes a valid XML.
• No checks if the embedded text is a valid type parameter.

Reflow XML Doc Comments

Reformats the XML doc comments according to the following rules:

• Re-wraps the XML doc comments according to the configured line length, e.g. 120 characters.

• Line breaks are avoided for supported nested tags.

• Top-level tags are re-ordered:

  1. <summary>...</summary>
  2. <typeparam name="...">...</typeparam> - according to the type parameter order
  3. <param name="...">...</param> - according to the parameter order
  4. <return>...</return>
  5. <value>...</value>
  6. <exception cref="...">...</exception>
  7. <remarks>...</remarks>
  8. <example>...</example>
  9. <seealso cref="">...</seealso> or <seealso href="">...</seealso>

• Some nested tags are indented if they contain sub-tags: <list>, <listheader>, <item>

• The following user settings are respected:

  • indent size
  • hard wrap at (line length)
  • inside of tag header
    • spaces around '=' in attribute
    • space after last attribute
    • space before '/>'

• The following user settings are intentionally ignored:

  • indent style - only "space" character is used
  • wrap long lines
  • wrap tags and processing instructions
  • inside of tag header:
    • attribute format
  • tag content...
  • around tags...

⚠️ Known Limitations

• Currently, only ///-style doc comments are supported
• The context action is only available for XML doc comments with valid tags. Tags are valid if they are well-known and have all required attributes (attribute values are not checked).
• The context action might remove empty lines in the <code>...</code> sections