Question

Microsoft拥有带有recommended set of tags的三斜杠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

在浏览source code on GitHub之后，一种模式开始出现，以下标签的非正式顺序似乎很常见：

summary
typeparam
param
returns
exception
remarks
example

其他观察：

true，false和null这些字词往往包含在<c>标记内。
有时但不总是网址在<c>标记内。
对类型的引用标有<see cref="Foo"/>标记。
对通用类型的引用标有<see cref="Bar{T}"/>标记。
对参数的引用标有<paramref name="name"/>标记。
对通用类型参数的引用标有<typeparamref name="T"/>标记。
句子以标点符号结束。
嵌套代码，例如<code>中的<example>，有时会缩进。

Answer 2

这些内联文档语句（参见XSD for XML documentation generated for C#?）生成的XML文档似乎没有正式的XML Schema，所以可能最好的答案是订单是否有所不同取决于你的内容想要使用那个XML文档。据我所知，大多数文档生成器不会对顺序产生影响，智能感知也不会产生差异。

除了技术后果之外，我同意遵守一些代码指南可能会有所帮助，但我也没有听说过一个被广泛接受的指南。

简而言之，我不认为有推荐的订购，因为订单不会产生任何影响，但您可以自由创建内部指南。

XML文档中的标签排序

2 个答案: