web-dev-qa-db-fra.com

Documentation XML pour un espace de noms

Voulez-vous écrire xml-doc pour un espace de noms? Et si oui, comment et où?

Je penserais, si cela est possible, peut-être un fichier presque vide comme ceci:

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

}

Mais ça va marcher? Puisque vous ... "déclarez", ou au moins utilisez l'espace de noms dans tous les autres fichiers également ... et que se passerait-il si vous écriviez quelque chose de la documentation xml ailleurs sur le même espace de noms? Serait-ce un parti? Ou seraient-ils fusionnés d'une manière ou d'une autre?

c#namespacesxml-documentation
51
Svish

NDoc le supporte en reconnaissant une classe NamespaceDoc spéciale située dans chaque espace de noms et en utilisant la documentation correspondante. Je n'ai pas essayé, mais Sandcastle semble supporter le même truc.

Edit: Par exemple:

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

Sandcastle ne prend pas directement en charge le NamespaceDoc, mais si vous utilisez Sandcastle Help File Builder vous pouvez utiliser la classe NamespaceDoc mentionnée par Tim.

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

SCHB étend également légèrement la syntaxe et permet d'intégrer des exemples de code directement à partir de fichiers de code. Un exemple _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>

Inclure la documentation dans un fichier XML vous permet d'écrire un bref résumé en code et une description plus détaillée dans un fichier XML séparé pour le fichier d'aide. De cette façon, le code n'est pas encombré de tous les détails et reste facilement lisible.

26
Mikko Rantanen

Sandcastle Help File Builder prend en charge les commentaires sur les espaces de noms. Ouvrez votre projet Sandcastle. Dans la fenêtre Project Properties, accédez à Summaries et cliquez sur le bouton Edit Namespace Summaries.

enter image description here

14
Norbert Szenasi

Vous pouvez le faire en doxygen en utilisant:

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

En outre, il est recommandé de déclarer vos espaces de nom dans un fichier NameSpaces.cs et de les commenter uniquement dans ce fichier.

1
Adrian Lopez

Il n'est pas possible de mettre des commentaires sur les espaces de noms.

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

0
Kirtan

Si vous utilisez le système de documentation Mono s mdoc , vous pouvez documenter les membres des espaces de noms en modifiant les fichiers de documentation ns - *. Xml.

Voir la documentation sur le format de fichier mdoc pour plus de détails.

0
jonp

Si vous utilisez Sandcastle et son "Générateur de fichiers d'aide", vous pouvez documenter les espaces de noms et les groupes d'espaces de noms à l'aide du code suivant dans vos projets:

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

Si le regroupement d'espaces de noms est activé dans le projet, vous pouvez également gérer les commentaires du groupe d'espaces de noms à l'aide d'une classe NamespaceGroupDoc de la même manière. Ce qui suit est un exemple:

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

Pour que la classe NamespaceDoc n'apparaisse pas dans le fichier d'aide, laissez le mot clé public et marquez-le avec un attribut CompilerGenerated. 

Pour référence, voir ici: https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

0
MarkusE