Documentation XML pour un espace de noms

Question

Rédigeriez-vous une xml-doc pour un espace de noms ? Et si oui, comment et où ?

Je penserais, si c'est possible, à un fichier presque vide comme celui-ci :

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

}

Mais cela fonctionnera-t-il ? 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 un truc de documentation xml ailleurs sur le même espace de noms ? L'un des deux serait-il supprimé ? Ou seraient-ils fusionnés d'une manière ou d'une autre ?

Answer 1

Le NDoc soutient cette démarche en reconnaissant une NamespaceDoc située dans chaque espace de noms, et d'utiliser la documentation qui s'y trouve. Je n'ai pas essayé, mais Sandcastle semble permettre la même chose.

Editer : Par exemple :

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

Answer 2

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
    {
    }
}

Le 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>

L'inclusion de la documentation dans un fichier XML vous permet de rédiger un bref résumé dans le code et une description plus détaillée dans un fichier XML distinct pour le fichier d'aide. De cette manière, le code n'est pas encombré par tous les détails et reste facilement lisible.

Answer 3

Sandcastle Help File Builder prend en charge les commentaires sur les espaces de noms. Ouvrez votre projet Sandcastle. Dans l'espace de Project Properties naviguer vers Summaries et cliquez sur l'icône Edit Namespace Summaries bouton.

Answer 4

Vous pouvez le faire dans doxygen en utilisant :

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

Il est également conseillé de déclarer vos espaces de noms dans un fichier NameSpaces.cs et de ne les commenter que dans ce fichier.

Answer 5

Si vous utilisez Sandcastle et son "Help File Builder", vous pouvez documenter les espaces de noms et les groupes d'espaces de noms en utilisant le 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. Voici 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 éviter que la classe NamespaceDoc n'apparaisse dans le fichier d'aide, supprimez le mot-clé public et marquez-la d'un attribut CompilerGenerated.

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