¿Documentación del espacio de nombres en un proyecto .Net (Sandcastle)?

Question

Empecé a usar Sandcastle hace algún tiempo para generar un sitio web de documentación para uno de nuestros proyectos. Funciona bastante bien, pero siempre hemos escrito documentación para clases, métodos, propiedades (...) en nuestro proyecto y teníamos una documentación completamente separada para el proyecto general y las partes / módulos / espacios de nombres del proyecto. Sería bueno si pudiera fusionar esa documentación y agregar la documentación respectiva a los archivos auxiliares generados, pero no puedo encontrar la manera de hacerlo.

Simplemente agregar comentarios a la declaración del espacio de nombres no parece funcionar (C #):

/// <summary>
/// My short namespace description
/// </summary>
namespace MyNamespace { ... }

¿Alguien sabe cómo hacer esto? Sé que es posible de alguna manera y sería realmente bueno tener ... :)

Answer 1

Sandcastle también es compatible con la documentación de espacio de nombres de estilo ndoc, que le permite pegar la documentación en los archivos de origen:

Simplemente cree una clase no pública llamada NamespaceDoc en el espacio de nombres que desea documentar, y el comentario de documentación xml para esa clase se utilizará para el espacio de nombres.

Adórnelo con un atributo [CompilerGenerated] para evitar que la clase misma aparezca en la documentación.

Ejemplo:

namespace Some.Test
{
    /// <summary>
    /// The <see cref="Some.Test"/> namespace contains classes for ....
    /// </summary>

    [System.Runtime.CompilerServices.CompilerGenerated]
    class NamespaceDoc
    {
    }
}

El elemento de trabajo en SandCastle se encuentra aquí.

Answer 2

Si usa Sandcastle Help File Builder hay un cuadro de diálogo para ingresar los resúmenes del espacio de nombres. (Aparentemente también es compatible con la definición de una clase específica, pero no lo preferiría ...)

De la lista de características:

  

Definición del resumen del proyecto y   comentarios de resumen del espacio de nombres que   aparecer en el archivo de ayuda. Tú también puedes   indicar fácilmente qué espacios de nombres   incluir o excluir del archivo de ayuda.   También se incluye soporte para   especificando comentarios de espacio de nombres a través de un   Clase NamespaceDoc dentro de cada   espacio de nombres.

Answer 3

Utilice Sandcastle Help File Builder . Permite especificar descripciones de espacios de nombres en el archivo de proyecto XML

Ejemplo :

<namespaceSummaryItem name="System" isDocumented="True">
    Generic interfaces and helper classes.
</namespaceSummaryItem>

Referencias:

• ejemplo de proyecto de código abierto que genera documentación con cada compilación (todos los scripts están en el tronco).
• Así es cómo la documentación de SHFB parece en la Web (se se implementa en cada compilación forzada)

.

Answer 4

Sé que es una publicación antigua, pero esto puede ser de ayuda para otra persona.

Siguiendo este enlace , puede establecer una descripción para los espacios de nombres sin la necesidad de agregar una clase no pública a su proyecto.

  

Para editar los resúmenes del espacio de nombres, expanda la sección Resúmenes dentro de la pestaña Propiedades del proyecto en SHFB. Verá una configuración llamada, & Quot; NamespaceSummaries & Quot ;, que inicialmente muestra el valor, & Quot; (None) & Quot ;. Haga clic en la configuración para seleccionarla y aparecerá un botón que muestra un símbolo de puntos suspensivos (...). Haga clic en este botón para mostrar el cuadro de diálogo Resúmenes del espacio de nombres, que se muestra a continuación:

Answer 5

No puede agregar referencias de esa manera: hágalo a través de instancias de NamespaceDoc.cs

es decir

/// <summary> /// Concrete implementation of see cref="IInterface" using see cref="Concrete"
/// </summary> class NamespaceDoc { }

ver aquí

Answer 6

Veo documentación para un " Archivos de comentarios XML externos " ;. Mostrando un esquema como:

<doc>
    <assembly/>
    <members>
        <member/>
    </members>
</doc>

Si esto se coloca en un archivo separado, ¿cuál sería la extensión (xml / aml) y se puede usar en el proyecto de Visual Studio?