訂購XML文檔中的標籤

Microsoft擁有三行斜槓XML文檔及其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>標籤始終應該是第一個標籤。

來源

2016-04-21 Fred

它們的主要目的是作爲元數據被Visual Studio拾取以提供更好的智能感知幫助，所以在正常使用下，順序無關緊要。很明顯，在你的代碼庫中你可能會關心。也許你可以在內部標準化GhostDoc的功能：http://submain.com/products/ghostdoc.aspx – briantyler

瀏覽source code on GitHub之後，格局開始出現和標籤的下列非正式順序似乎是很常見的：

summary
typeparam
param
returns
exception
remarks
example

其他意見：

詞語true，false和null傾向於在<c>標籤內纏繞。
有時但不總是URL位於<c>標記內。
對物體的引用標記爲<see cref="Foo"/>標記。
對參數的引用標有<paramref name="name"/>標記。
對通用類型參數的引用標記爲<typeparamref name="name"/>標記。
句子以標點符號結尾。
在<example>內的嵌套標記，例如<code>有時會縮進。

來源

2016-04-21 12:19:22 Fred

這些內聯文檔語句（參見XSD for XML documentation generated for C#?）生成的XML文檔似乎沒有官方的XML Schema，所以最好的答案是訂單是否有所作用取決於您想要做什麼與該XML文檔。據我所知，大多數文檔生成器不會影響順序，IntelliSense也不會。

除了技術上的影響，我同意遵守一些代碼準則可能會有所幫助，但我也沒有聽說過一個被廣泛接受的準則。

所以總之，我不認爲有推薦的訂購，因爲訂單不會有所作爲，但您可以自由創建內部指南。

來源

2016-04-21 10:43:33 Georg

訂購XML文檔中的標籤

回答

相關問題