XML-documentation for a namespace

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

yo creo, si es posible, tal vez un archivo casi vacío así:

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

}

Pero ¿Funcionará? Ya que ... "declara", o al menos usa también el espacio de nombres en todos los otros archivos ... ¿y qué pasaría si escribiera una cosa de documentación xml en otro lugar en el mismo espacio de nombres? ¿Se habría ido uno? ¿O se fusionarían de alguna manera?

Fuente

2009-04-27 Svish

NDoc apoya esta reconociendo una clase especial NamespaceDoc situada en cada espacio de nombres, y utilizando la documentación de eso. No lo he intentado, pero Sandcastle parece apoyar el mismo truco.

Editar: Por ejemplo:

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

Fuente

2009-04-27 12:13:58

Entonces, NamespaceDoc directamente? ¿Pongo uno en cada directorio y luego algo? Para tener un comentario para cada uno de ellos ... – Svish

Sí, pegaré un ejemplo en mi respuesta. –

El uso de público en lugar de interno hará que esta clase también aparezca en la ayuda, lo que es malo. –

No es posible poner comentarios en espacios de nombres.

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

Fuente

2009-04-27 12:10:01 Kirtan

castillo de arena no es compatible con el NamespaceDoc directamente, pero si se utiliza Sandcastle Help File Builder se puede utilizar la clase NamespaceDoc mencionado por Tim.

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

SCHB también extiende la sintaxis ligeramente y permite incrustar ejemplos de código directamente desde los 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>

incluyendo documentación en el archivo XML permite escribir breve resumen en el código y la descripción más grande en un archivo XML independiente para el archivo de ayuda. De esta forma, el código no está desordenado con todos los detalles y sigue siendo fácilmente legible.

Fuente

2009-04-27 12:27:53

Interesante ... ¿Por qué "Documentation/*" como ruta? – Svish

Oh. Es una expresión XPath para el _Namespace.xml. Es posible almacenar toda la documentación en el mismo archivo XML y simplemente incluir estos en función de su ruta, es decir. path = 'Documentation/Namespace/*', etc. El XML de ejemplo utiliza la etiqueta raíz 'Documentation/*' y es específico de la clase por lo que la ruta solo incluye todo dentro de la etiqueta raíz. –

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

Consulte el mdoc file format documentation para obtener más información.

Fuente

2009-09-22 02:32:16 jonp

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

enter image description here

Fuente

2014-09-12 16:19:37

Perfecto, ¡justo lo que estaba buscando! – Omaer

Puede hacerlo en doxygen usando:

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

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

Fuente

2016-02-29 22:10:37

Respuesta

Cuestiones relacionadas