Documentación del espacio de nombres en a.Net proyecto (Castillo de arena)?
Comencé 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 solo documentación para clases, métodos, propiedades (...) en nuestro proyecto y tenía 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 de ayuda generados, pero no puedo averiguar cómo haciéndolo.
Simplemente agregar comentarios a la declaración de 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 muy bueno tenerlo... :)
6 answers
Sandcastle también admite la documentación de espacio de nombres de estilo ndoc, que le permite pegar la documentación en los archivos fuente:
Simplemente cree una clase no pública llamada NamespaceDoc en el espacio de nombres que desea documentar, y el comentario xml doc de esa clase se utilizará para el espacio de nombres.
Adórnelo con un atributo [CompilerGenerated] para evitar que la propia clase 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 Castillo de arena se encuentra aquí.
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2009-05-13 09:49:25
Si utiliza Sandcastle Help File Builder hay un diálogo para introducir los resúmenes de los espacios de nombres. (Aparentemente también apoyo para definir una clase específica, pero no lo preferiría..)
De la lista de características:
Definición del resumen del proyecto y namespace summary comments that will aparece en el archivo de ayuda. También puede indicar fácilmente qué espacios de nombres incluir o excluir del archivo de ayuda. También se incluye soporte para especificar el espacio de nombres comentarios vía a Clase NamespaceDoc dentro de cada espacio de nombres.
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2008-10-01 08:17:20
Use 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 por SHFB parece en la Web (se se despliega en cada compilación forzada)
.
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2008-10-01 08:55:54
Sé que es un post antiguo, pero esto puede ser de ayuda para alguien más.
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, "NamespaceSummaries", que inicialmente muestra el valor,"(None)". Haga clic en el ajuste para seleccionarlo y un botón que muestra un símbolo de puntos suspensivos (...) aparecer. Haga clic en este botón para mostrar el cuadro de diálogo Resúmenes de espacios de nombres, que se muestra a continuación:
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2016-08-08 15:55:04
No puede agregar referencias de esa manera, hágalo a través de NamespaceDoc.instancias cs
Es decir
/// <summary>
/// Concrete implementation of see cref="IInterface" using see cref="Concrete"
/// </summary>
class NamespaceDoc
{
}
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2014-04-28 10:47:57
Veo documentación para un "Archivo de Comentarios XML externo". Mostrando un esquema como:
<doc>
<assembly/>
<members>
<member/>
</members>
</doc>
Si 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?
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2018-02-01 22:00:23