XML 文档中标签的排序

Question

Microsoft 有三斜杠 XML 文档及其推荐的标签集。

如果标签的顺序在不同的使用位置不同，那就很奇怪了。

所以我想知道 XML 标签是否有任何推荐的排序？

例子：

/// <summary>Performs a foo calculation.</summary>
/// <param name="baseValue">The base value.</param>
/// <param name="af">The amplification factor.</param>
/// <returns>The supposed calculation.</returns>
/// <exception cref="ArgumentException"><paramref name="af"/> is negative.</exception>
/// <remarks>According to the theory laid forward by Dr. Hans Foo in 1732.</remarks>
/// <example>
/// Performs a foo calculation using a amplification factor of 10.
/// <code>var value = Foo(512, 10);</code>
/// </example>
public decimal Foo(int baseValue, decimal af) { /* ... */ }

现在，我只假设该<summary>标签始终应该是第一个标签。

Answer 1

在 GitHub 上浏览源代码后，一种模式开始出现，以下非正式的标签顺序似乎很常见：

1. summary
2. typeparam
3. param
4. returns
5. exception
6. remarks
7. example

其他观察结果：

• 单词true,false和null往往包含在<c>标签内。
• 有时但并非总是 URL 位于<c>标记内。
• 对类型的引用用标签标记<see cref="Foo"/>。
• 对泛型类型的引用用标签标记<see cref="Bar{T}"/>。
• 对参数的引用用<paramref name="name"/>标签标记。
• 对泛型类型参数的引用用标签标记<typeparamref name="T"/>。
• 句子以标点符号结尾。
• 嵌套标签（例如<code>在 内<example>）有时会缩进。