命名空间的 XML 文档

发布于 2024-07-18 20:45:30 字数 327 浏览 10 评论 0原文

您会为命名空间编写 xml-doc 吗？如果是，如何以及在哪里？

我想，如果可能的话，也许是一个几乎空的文件，如下所示：

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

}

但这会起作用吗？既然您...“声明”，或者至少在所有其他文件中也使用该名称空间...如果您在同一名称空间的其他地方编写了 xml 文档，会发生什么情况？会有一个消失吗？或者它们会以某种方式合并吗？

原文

Would you write xml-doc for a namespace? And if yes, how and where?

I would think, if it is possible, maybe an almost empty file like this:

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

}

But will that work? Since you... "declare", or at least use the namespace in all the other files as well... and what would happen if you wrote an xml-documentation thing somewhere else on the same namespace? Would one be gone? Or would they be merged somehow?

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

π浅易 2024-07-25 20:45:31

NDoc 通过识别位于每个命名空间中的特殊 NamespaceDoc 类并使用其中的文档来支持这一点。我还没有尝试过，但 Sandcastle 似乎支持同样的技巧。

编辑：
例如：

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

NDoc supports this by recognising a special NamespaceDoc class located in each namespace, and using the documentation from that. I haven't tried it, but Sandcastle appears to support the same trick.

Edit:
For example:

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

回复收藏 0 原文

泅渡 2024-07-25 20:45:31

Sandcastle 不直接支持 NamespaceDoc，但是如果您使用 Sandcastle 帮助文件生成器，您可以使用提到的 NamespaceDoc 类由蒂姆.

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

SCHB 还稍微扩展了语法，并允许直接从代码文件嵌入代码示例。示例 _Namespace.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 文件中编写较大的描述。这样，代码就不会因所有细节而混乱，并且仍然易于阅读。

Sandcastle does not support the NamespaceDoc directly, but if you use Sandcastle Help File Builder you can use the NamespaceDoc class mentioned by Tim.

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

SCHB also extends the syntax slightly and allows embedding code examples straight from code files. An example _Namespace.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>

Including documentation in XML file allows you to write short summary in code and larger description in a separate XML file for the help file. This way the code isn't cluttered with all the details and remains easily readable.

回复收藏 0 原文

亣腦蒛氧 2024-07-25 20:45:31

Sandcastle 帮助文件生成器支持命名空间上的注释。打开您的 Sandcastle 项目。在Project Properties 窗口中导航至Summaries 并单击Edit Namespace Summaries 按钮。

在此处输入图像描述

回复收藏 0 原文

甜是你 2024-07-25 20:45:31

您可以在 doxygen 中使用以下方法执行此操作：

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

另外，在 NameSpaces.cs 文件中声明名称空间并仅在此文件中注释它们是一个很好的做法。

You can do it in doxygen using:

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

Also, it's a good practice to declare your namespaces in a NameSpaces.cs file, and comment them only in this file.

回复收藏 0 原文

捎一片雪花 2024-07-25 20:45:31

如果您使用 Sandcastle 及其“帮助文件生成器”，您可以在项目中使用以下代码记录命名空间和命名空间组：

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 关键字并用 CompilerGenerate 属性对其进行标记。

有关参考，请参阅此处： https://ewsoftware.github .io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

If you use Sandcastle and its "Help File Builder" you can document namespaces and Namespace-Groups using the following Code in your Projects:

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

If the project has namespace grouping enabled, you can also maintain the namespace group comments using a NamespaceGroupDoc class in a similar fashion. The following is an example:

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

To keep the NamespaceDoc class from appearing in the help file, leave off the public keyword and mark it with a CompilerGenerated attribute.

For Reference see here: https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

回复收藏 0 原文

缱倦旧时光 2024-07-25 20:45:31

无法对命名空间添加注释。

在 http://ndoc.sourceforge.net/content/documenters.htm 上使用NamespaceDocSummaries

回复收藏 0 原文

长安忆 2024-07-25 20:45:31

如果使用 Mono 的 mdoc 文档系统，您可以通过编辑 ns-*.xml 文档文件来记录命名空间成员。

请参阅 mdoc 文件格式文档更多细节。

回复收藏 0 原文

请爱~陌生人 2024-07-25 20:45:31

在 Visual Studio 中，可以通过创建如下所示的 Namespaces.cs 文件来完成：

// This file is inteded to only create the namspace comments.
// Therefore the warnig 'CS1587: XML comment is not placed on a valid language element'
// must be disabled for this file.
#pragma warning disable CS1587

// --------------------------------------------------------------

/// <summary>
/// This namespace implements the IO functionality for MyProduct
/// </summary>
namespace MyCompany.MyProduct.IO { };

// --------------------------------------------------------------
// Restore warning
#pragma warning restore CS1587

In Visual Studio it can be done by creating a Namespaces.cs file like the following:

// This file is inteded to only create the namspace comments.
// Therefore the warnig 'CS1587: XML comment is not placed on a valid language element'
// must be disabled for this file.
#pragma warning disable CS1587

// --------------------------------------------------------------

/// <summary>
/// This namespace implements the IO functionality for MyProduct
/// </summary>
namespace MyCompany.MyProduct.IO { };

// --------------------------------------------------------------
// Restore warning
#pragma warning restore CS1587

回复收藏 0 原文

~没有更多了~