¿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. Está funcionando bastante bien, pero siempre hemos escrito documentación para clases, métodos, propiedades (...) en nuestro proyecto y teníamos documentación completamente separada para el proyecto en general y las partes del proyecto/módulos/espacios de nombres. 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 añadiendo comentarios a la declaración de espacio de nombres no parecen 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 muy bueno tener ... :)

Answer 1

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

Basta con crear una clase que no sea pública llamada NamespaceDoc en el espacio de nombres que desea documentar, y el xml el comentario del doc para esa clase se usará para el espacio de nombres.

Adornalo con un atributo [CompilerGenerated] para evitar que la clase se muestre 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 here.

Answer 2

Si usas Sandcastle Help File Builder, hay un cuadro de diálogo para ingresar los resúmenes del Espacio de nombres. (Al parecer también apoyo para la definición de una clase específica, pero no preferiría que ..)

En la lista de programas:

Definición de resumen del proyecto y de espacio de nombres comentarios resumen que aparece en la archivo de ayuda. También puede indicar fácilmente qué espacios de nombres para incluyen o excluyen del archivo de ayuda. También se incluye soporte para especificando los comentarios del espacio de nombres a través de una clase NamespaceDoc dentro de cada espacio de nombre .

Answer 3

Use Sandcastle Help File Builder. Permite especificar descripciones de espacio de nombres en el archivo de proyecto XML

Ejemplo:

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

Referencias:

• example of Open Source project que genera la documentación con cada generación (todos los scripts están en el tronco ).
• eso es how the documentation by SHFB looks like on the Web (que se implementa en cada generación forzada)

.

Answer 4

usted no puede agregar referencias de esa manera - lo hacen a través de las instancias NamespaceDoc.cs

es decir

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

see here

Answer 5

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

Following this link, 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 de Resúmenes en la pestaña Propiedades del proyecto en SHFB. Verá una configuración llamada, "NamespaceSummaries", que inicialmente muestra el valor "(None)". 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 Espacio de nombres resúmenes, se muestra a continuación:

Answer 6

veo la documentación de una "XML externo Comentarios archivos". Que muestra un esquema como:

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

Si esto se coloca en un archivo separado, lo que podría ser la extensión (XML/AML) y puede esto ser utilizado en el proyecto de Visual Studio?