XML Doc Comments - prodot/ReCommended-Extension GitHub Wiki

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.

Important

Known Limitations

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.

Important

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.

Important

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.

Important

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...

Important

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
⚠️ **GitHub.com Fallback** ⚠️