.NET xml docs - 繼承文檔

Question

NDoc有一個XML元素inheritdoc ，它允許您從父類（或實現的接口）繼承成員的文檔。 但是，Visual Studio（即C＃編譯器）不理解此標記並抱怨文檔不存在或完整。 StyleCop和其他一些工具也是如此。 有替代方法嗎？ 你如何保持文檔完整，但沒有重復XML描述？

Answer 1

我有一個更好的答案： FiXml 。

使用GhostDoc克隆注釋肯定是有效的方法，但它有很多缺點，例如：

• 當原始注釋被更改（在開發期間經常發生）時，其克隆不是。
• 你正在制作大量的副本。 如果您使用任何源代碼分析工具（例如Team City中的Duplicate Finder），它將主要找到您的評論。

FiXml的簡短描述：它是由C＃\\ Visual Basic .Net生成的XML文檔的后處理器。 它作為MSBuild任務實現，因此很容易將它集成到任何項目中。 它解決了與使用以下語言編寫XML文檔相關的一些惱人案例：

• 不支持從基類或接口繼承文檔。 即任何被覆蓋成員的文檔都應該從頭開始編寫，盡管通常至少要繼承它的一部分是非常可取的。
• 不支持插入常用的文檔模板 ，例如“此類型是單例 - 使用其<see cref="Instance" />屬性來獲取它的唯一實例。”或甚至“初始化<CurrentType>的新實例<CurrentType>上課。“

要解決上述問題，請提供以下附加XML標記：

• <inheritdoc />, <inherited />標簽
• <see cref="..." copy="..." /> <see/>標簽中的<see cref="..." copy="..." />屬性。

這是它的網頁和下載頁面 （斷開的鏈接）。

最后， Sandcastle中有<inheritdoc>標簽 - 使用它比復制XML注釋更好，但與FiXml相比它有一些缺點：

• Sandcastle生成編譯的HTML幫助文件 - 它不會修改包含提取的XML注釋的.xml文件。 但是許多工具都使用這些文件，包括.NET Reflector和Visual Studio .NET中的類browser \\ IntelliSense。 因此，如果您只使用Sandcastle，那么您將看不到繼承的文檔。
• Sandcastle的實施功能不那么強大。 例如，沒有<see ... copy="true" /> 。

有關更多詳細信息，請參閱Sandcastle的<inheritdoc>說明 。

Answer 2

另一種方法是使用GhostDoc - 一個Visual Studio的加載項，可以自動為您生成注釋。 這當然會復制XML描述，這是您要避免的一部分 - 但至少它會自動為您完成。

如果您完全不使用繼承的方法或覆蓋接口方法，那么會發生什么？ 我懷疑它取決於你如何配置NDoc，但肯定在MSDN文檔中似乎只是自然地繼承了文檔 - 並且快速檢查表明當你不為繼承方法生成文檔時VS不會發出警告。 值得一試，當然。

Answer 3

我構建了一個命令行工具來對XML文檔文件進行后處理，以添加對<inheritdoc />標記的支持。

它對源代碼中的Intellisense沒有幫助，但它確實允許修改后的XML文檔文件包含在NuGet包中，因此可以在引用的NuGet包中使用Intellisense。

有關詳細信息，請訪問www.inheritdoc.io （提供免費版本）。