.net - sirve - tipos de namespace
¿Documentación del espacio de nombres en un proyecto.Net(Sandcastle)? (5)
Empecé a utilizar Sandcastle hace un 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 piezas / 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 como hacer esto? Sé que es posible de alguna manera y sería genial tener ... :)
Si utiliza el Creador de archivos de ayuda de Sandcastle, hay un cuadro de diálogo para ingresar los resúmenes del Espacio de nombres. (Aparentemente también soporte para definir una clase específica, pero no lo prefiero ...)
De la lista de características:
Definición de resumen de proyecto y comentarios de resumen de espacio de nombre que aparecerán en el archivo de ayuda. También puede indicar fácilmente qué espacios de nombres incluir o excluir del archivo de ayuda. El soporte también se incluye para especificar comentarios del espacio de nombres a través de una clase NamespaceDoc dentro de cada espacio de nombres.
Utilice el Creador de archivos de ayuda de Sandcastle . 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
- ejemplo de proyecto de código abierto que genera documentación con cada compilación (todos los guiones están en el tronco).
- Así es como se ve la documentación de SHFB en la Web (se implementa en cada compilación forzada)
.
Sandcastle también admite la documentación del espacio de nombres de estilo ndoc, que le permite incluir 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 doc. Xml para esa clase se usará para el espacio de nombres.
Adórnelo 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 aquí.
No puede agregar referencias de esa manera; hágalo a través de las instancias de NamespaceDoc.cs
es decir
/// <summary> /// Concrete implementation of see cref="IInterface" using see cref="Concrete"
/// </summary> class NamespaceDoc { }
Sé que es una publicación anterior, 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 que no sea 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, "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 Resúmenes del espacio de nombres, que se muestra a continuación:
