generate - params comments c#

XML-documentación para un espacio de nombres

Question

¿Escribirías xml-doc para un espacio de nombres? Y si es así, ¿cómo y dónde?

Pensaría, si es posible, tal vez un archivo casi vacío como este:

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

}

Pero, ¿funcionará? Ya que ... "declarar", o al menos usar el espacio de nombres en todos los demás archivos también ... ¿y qué pasaría si escribieras un documento de XML en otro lugar en el mismo espacio de nombres? ¿Se habría ido uno? ¿O se fusionarían de alguna manera?

Answer 1

NDoc admite esto reconociendo una clase de NamespaceDoc especial ubicada en cada espacio de nombres, y utilizando la documentación de eso. No lo he probado, pero Sandcastle parece apoyar el mismo truco.

Edición: por ejemplo:

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

Answer 2

No es posible poner comentarios en espacios de nombres.

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

Answer 3

Puedes hacerlo en doxygen usando:

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

Además, es una buena práctica declarar sus espacios de nombres en un archivo NameSpaces.cs y comentarlos solo en este archivo.

Answer 4

Sandcastle Help File Builder admite comentarios en espacios de nombres. Abre tu proyecto Sandcastle. En la ventana Project Properties , navegue hasta Summaries y haga clic en el botón Edit Namespace Summaries .

Answer 5

Sandcastle no admite el NamespaceDoc directamente, pero si usa Sandcastle Help File Builder , puede usar la clase NamespaceDoc mencionada por Tim.

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

SCHB también amplía ligeramente la sintaxis y permite incrustar ejemplos de código directamente desde archivos de código. Un ejemplo _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>

La inclusión de documentación en el archivo XML le permite escribir un breve resumen en el código y una descripción más amplia en un archivo XML separado para el archivo de ayuda. De esta manera, el código no está desordenado con todos los detalles y se puede leer fácilmente.

Answer 6

Si usa Sandcastle y su "Generador de archivos de ayuda", puede documentar espacios de nombres y grupos de espacios de nombres usando el siguiente código en sus proyectos:

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

Si el proyecto tiene habilitada la agrupación de espacios de nombres, también puede mantener los comentarios del grupo de espacios de nombres utilizando una clase NamespaceGroupDoc de manera similar. Lo siguiente es un ejemplo:

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

Para evitar que la clase NamespaceDoc aparezca en el archivo de ayuda, deje de lado la palabra clave pública y márquela con un atributo CompilerGenerated.

Para referencia, consulte aquí: https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

Answer 7

Si usa el sistema de documentación mdoc Mono , puede documentar los miembros del espacio de nombres editando los archivos de documentación ns - *. Xml.

Consulte la documentación en formato de archivo mdoc para obtener más detalles.