代码之家 › 专栏 › 技术社区 › simendsjo

如何注释命名空间[duplicate]

.net c#

simendsjo · 技术社区 · 14 年前

我想,如果可能的话,可能是这样一个几乎空的文件:

/// <summary>
/// This namespace contains stuff
/// </summary>
namespace Some.Namespace
{

}

但这行得通吗?既然你……”声明”,或者至少在所有其他文件中使用名称空间。。。如果您在同一个名称空间的其他地方编写了xml文档,会发生什么情况呢?会有人走吗?还是会合并?

0 回复 | 直到 12 年前

Tim Robinson 15 年前

NDoc通过识别一个特殊的 NamespaceDoc 类,并使用该命名空间中的文档。我没试过,但桑德卡斯尔似乎也支持同样的伎俩。

例如:

namespace Some.Namespace
{
    /// <summary>
    /// This namespace contains stuff
    /// </summary>
    public static class NamespaceDoc
    {
    }
}

Mikko Rantanen 15 年前

Sandcastle不直接支持NamespaceDoc,但是如果使用 Sandcastle Help File Builder

namespace Example
{
    /// <summary>
    ///   <para>
    ///     Summary
    ///   </para>
    /// </summary>
    /// <include file='_Namespace.xml' path='Documentation/*' />
    internal class NamespaceDoc
    {
    }
}

SCHB还稍微扩展了语法,允许直接从代码文件中嵌入代码示例。一个例子_命名空间.xml:

<?xml version="1.0" encoding="utf-8" ?>
<Documentation>
  <summary>
    <h1 class="heading">Example Namespace</h1>
    <para>
      This namespace is used in the following way:
    </para>

    <code source="Examples\Class.cs" lang="cs"></code>
    <code source="Examples\Class.vb" lang="vbnet"></code>

    <para>
      Hopefully this helps!
    </para>
  </summary>
</Documentation>

通过在XML文件中包含文档,您可以在单独的XML文件中为帮助文件编写简短的代码摘要和更大的描述。这样,代码就不会被所有的细节弄得乱七八糟,而且很容易阅读。

Norbert Szenasi 10 年前

Sandcastle帮助文件生成器支持对名称空间的注释。打开你的Sandcastle项目。在 Project Properties Summaries 然后单击 Edit Namespace Summaries

enter image description here

Adrian Lopez 8 年前

/// <summary>
/// description
/// </summary>
namespace name{};

另外,在名称空间.cs文件,并仅在此文件中对其进行注释。

MarkusE 6 年前

namespace Company.Product.Widgets
{
    /// <summary>
    /// These are the namespace comments for <c>Company.Product.Widgets</c>.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceDoc
    {
    }
}

如果项目启用了命名空间分组,则还可以使用NamespaceGroupDoc类以类似的方式维护命名空间组注释。以下是一个例子:

namespace Company.Product
{
    /// <summary>
    /// These are the group comments for namespaces in <c>Company.Product</c>.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceGroupDoc
    {
    }
}

要防止NamespaceDoc类出现在帮助文件中,请去掉public关键字并用CompilerGenerated属性标记它。

参考如下: https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

Kirtan 15 年前

不可能在名称空间上添加注释。

UseNamespaceDocSummaries on http://ndoc.sourceforge.net/content/documenters.htm

jonp 15 年前

Mono 的 mdoc

见 mdoc file format documentation 更多细节。