web-dev-qa-db-ja.com

名前空間のXMLドキュメント

名前空間のxml-docを記述しますか？そして、もしそうなら、どこでどのように？

可能であれば、おそらく次のようなほとんど空のファイルだと思います。

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

}

しかし、それでうまくいくでしょうか？あなたが...「宣言」するか、少なくとも他のすべてのファイルでも名前空間を使用しているので...そして同じ名前空間の他の場所にxml-documentationを書いた場合どうなるでしょうか？ 1つはなくなりますか？または、それらはどういうわけかマージされますか？

c#namespacesxml-documentation
52
Svish

NDocは、各名前空間にある特別なNamespaceDocクラスを認識し、そこからドキュメントを使用することにより、これをサポートします。私はまだ試していませんが、Sandcastleは同じトリックをサポートしているようです。

編集：例：

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

SandcastleはNamespaceDocを直接サポートしていませんが、 Sandcastle Help File Builder を使用すると、Timが言及した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ファイルに大きな説明を書き込むことができます。このようにして、コードがすべての詳細で雑然とするのではなく、簡単に読み取ることができます。

27
Mikko Rantanen

Sandcastle Help File Builderは、名前空間に関するコメントをサポートしています。 Sandcastleプロジェクトを開きます。 Project PropertiesウィンドウでSummariesに移動し、Edit Namespace Summariesボタンをクリックします。

enter image description here

16
Norbert Szenasi

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キーワードを省略して、CompilerGenerated属性でマークします。

参照については、こちらを参照してください： https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

1
MarkusE

あなたはdoxygenでそれを行うことができます：

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

また、名前空間をNameSpaces.csファイルで宣言し、このファイルでのみコメントを付けることをお勧めします。

1
Adrian Lopez

名前空間にコメントを付けることはできません。

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

0
Kirtan

Mono の mdoc ドキュメンテーションシステムを使用している場合は、ns-*。xmlドキュメンテーションファイルを編集することで名前空間のメンバーをドキュメント化できます。

詳細は mdocファイル形式のドキュメント を参照してください。

0
jonp