XML 文档中标记的排序

本文关键字：排序 文档 XML | 更新日期: 2024-11-01 03:21:53

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>标签总是应该是第一个标签。

XML 文档中标记的排序

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

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

其他观察结果：

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

这些内联文档语句生成的 XML 文档似乎没有官方的 XML 模式（参见为 C# 生成的 XML 文档的 XSD？），因此可能最好的答案是顺序是否有所不同取决于您要对该 XML 文档执行的操作。据我所知，大多数文档生成器不会对顺序产生影响，IntelliSense 也不会。

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

所以简而言之，我认为没有推荐的订购，因为订单不会有什么不同，但您可以自由创建内部指南。

相关文章：