.Net 項目 (Sandcastle) 上的命名空間文檔？

Question

我前段時間開始使用Sandcastle為我們的一個項目生成一個文檔網站。 它運行良好，但我們始終只為項目中的類、方法、屬性（...）編寫文檔，並且為整個項目和項目部件/模塊/命名空間提供完全獨立的文檔。 如果我可以將這些文檔合並在一起並將相應的文檔添加到生成的幫助文件中，那就太好了，但我不知道該怎么做。

僅向命名空間聲明添加注釋似乎不起作用（C#）：

/// <summary>
/// My short namespace description
/// </summary>
namespace MyNamespace { ... }

有誰知道如何做到這一點？ 我知道以某種方式是可能的，擁有......真的很棒：)

Answer 1

Sandcastle 還支持 ndoc 樣式的命名空間文檔，它允許您將文檔粘貼在源文件中：

只需在要記錄的命名空間中創建一個名為 NamespaceDoc 的非公共類，該類的 xml doc 注釋將用於命名空間。

用 [CompilerGenerated] 屬性裝飾它以防止類本身出現在文檔中。

例子：

namespace Some.Test
{
    /// <summary>
    /// The <see cref="Some.Test"/> namespace contains classes for ....
    /// </summary>

    [System.Runtime.CompilerServices.CompilerGenerated]
    class NamespaceDoc
    {
    }
}

SandCastle 中的工作項位於此處。

Answer 2

如果您使用Sandcastle 幫助文件生成器，則會有一個對話框用於輸入命名空間摘要。 （顯然也支持定義一個特定的類，但我不喜歡它......）

從功能列表：

將出現在幫助文件中的項目摘要和命名空間摘要注釋的定義。 您還可以輕松地指明要在幫助文件中包含或排除哪些名稱空間。 還支持通過每個命名空間內的 NamespaceDoc 類指定命名空間注釋。

Answer 3

使用Sandcastle 幫助文件生成器。 它允許在 XML 項目文件中指定命名空間描述

例子：

<namespaceSummaryItem name="System" isDocumented="True">
    Generic interfaces and helper classes.
</namespaceSummaryItem>

參考：

• 每次構建生成文檔的開源項目示例（所有腳本都在主干中）。
• 這就是SHFB 的文檔在 Web 上的樣子（它部署在每個強制構建中）

.

Answer 4

我知道這是一個舊帖子，但這可能對其他人有幫助。

按照此鏈接，您可以為命名空間設置描述，而無需向項目添加非公共類。

要編輯命名空間摘要，請展開 SHFB 中項目屬性選項卡中的摘要部分。 您將看到一個名為“NamespaceSummaries”的設置，它最初顯示值“(None)”。 單擊設置以將其選中，然后會出現一個顯示省略號 (...) 的按鈕。 單擊此按鈕可顯示“命名空間摘要”對話框，如下圖所示：

Answer 5

您不能以這種方式添加引用 - 通過 NamespaceDoc.cs 實例來添加

IE

/// <summary> /// Concrete implementation of see cref="IInterface" using see cref="Concrete"
/// </summary> class NamespaceDoc { }

看這里

Answer 6

我看到了“外部 XML 注釋文件”的文檔。 顯示如下模式：

<doc>
    <assembly/>
    <members>
        <member/>
    </members>
</doc>

如果將其放在單獨的文件中，那么擴展名是什么 (xml/aml) 並且可以在 Visual Studio 項目中使用它嗎？

Answer 7

這是 Tuinstoelen 接受的答案中顯示的 C# 代碼片段的 VB.Net 版本。

我將這個答案留給那些在 Google 上發現這個問題並需要 VB 版本的人，因為如果您嘗試直接從 C# 中翻譯，則需要等待。

Namespace Global.TestNamespace
    ''' <summary>
    ''' The <see cref="TestNamespace"/> namespace contains classes for ....
    ''' </summary>
    <System.Runtime.CompilerServices.CompilerGeneratedAttribute()>
    Class NamespaceDoc
    End Class
End Namespace

注意“全局”。 前置到要記錄的命名空間。 至少對於我的 VB 項目配置，這是必要的，以便命名空間的名稱不會嵌套在根命名空間內，而是根命名空間的名稱。 在我添加“Global.”之前，編譯器正在生成“TestNamespace.TestNamespace”的摘要，而不僅僅是“TestNamespace”。 鑒於編譯器生成的 XML 文件中的信息不正確，SandCastle 無法將摘要識別為屬於正確的命名空間。