El uso de atributos de Documentación en C#

En el MSDN Attributes Tutorial que utilizan Author como un ejemplo de un atributo:El uso de atributos de Documentación en C#

[Author("Jane Programmer", Version = 2), IsTested()] 
class Order 
{ 
    // add stuff here ... 
}

Esto me parecían ser una buena idea, ya que le permitiría utilizar la reflexión para las clases de grupo por autor (por ejemplo): exponiendo efectivamente los metadatos que normalmente estarían en la documentación del compilador, lo que podría ser útil. Inmediatamente pensé "AHA que debería usar atributos para toda mi documentación en línea bloque!" - ej .:

[Author("Me")] 
[Description("Add 1 to value")] 
[Param("value", "The original value to add 1 to")] 
public int AddOne(value) {return value + 1;}

Sin embargo, ninguno of the answers que pude encontrar acerca de la documentación y los atributos parecen sugerir este método. Todos usan XML para la documentación en línea.

¿Hay atributos incorporados para ayudar con la documentación en línea? Si no, hay bibliotecas/paquetes que incluyen conjuntos de atributos predefinidos para la documentación en línea?

Fuente

2012-10-01 Robin Winslow

Hay muchas bibliotecas y paquetes que se ocupan de la documentación XML. – Jodrell

¿De verdad necesita encontrar esa información por reflexión? ¿Por qué no combina la conocida documentación xml y algún control de versión de código fuente (svn muestra exactamente lo que se ha hecho)? En tu caso, ¿qué pasa si dos desarrolladores cambiaron el mismo método/clase? –

No es una buena idea, IMO, ya que normalmente no necesita la documentación en tiempo de ejecución. La documentación XML ya es lo suficientemente fea como es, este enfoque sería aún más feo. Intenta imaginar un método más complejo donde la descripción consta de pocos párrafos. ¿Cómo sería eso con atributos? –

Algunas desventajas de mantener la documentación de atributos:

pobres formato para textos largos;
no es compatible con los complementos de Visual Studio (por ejemplo, utilizando la función de vista previa de la documentación de ReSharper);
no es compatible con herramientas de generación de documentación de terceros;
inclusión de documentación en ensamblajes que facilita considerablemente la ingeniería inversa;
duplicación de metadatos en códigos fuente con metadatos almacenados en un sistema de control de versiones (no tiene sentido seguir el autor y la versión de declaración en el código fuente, cuando el VCS proporciona información mucho más precisa - VCS no mienta)

No puedo pensar en ninguna ventaja en este momento. En caso de que lo necesite realmente, siempre es posible analizar los comentarios de la documentación XML y transformar toda la base de código en cualquier forma atribuida.

Fuente

2012-10-01 10:02:47

Todavía no estoy seguro de que el formateo de bloques largos de texto sea aún peor. Estoy de acuerdo con su punto de mantener la información del autor en control de versiones, pero eso es sobre qué documentar en lugar de cómo, este método aún podría ser útil para los parámetros. Los otros argumentos son simplemente acerca del soporte actual, que está cediendo a una estructura de control muy descendente en la evolución de C#, pero creo que tienes razón, esta no es una batalla que pueda ganar. Nunca voy a documentar adecuadamente mis clases, porque me rompe el corazón crear algo tan feo. Oh bien. –

Entonces debe buscar resolver el problema * dentro de usted * ;-) La documentación adecuada es una cuestión de disciplina en primer lugar. El formateo es segundo. Sin embargo, es una batalla cuesta arriba deshacerse de los comentarios de XML. Tal vez podría comenzar con la adquisición de un complemento auxiliar como ReSharper para facilitar la escritura de comentarios XML. –

Existe un caso de uso excelente para la documentación en atributos: documentación del usuario final en tiempo de ejecución. Por ejemplo, cuando tiene un gran conjunto de comandos de consola, puede almacenar la descripción de los comandos en atributos y extraer esta descripción para MyApp --help. – Tomas

La pregunta aquí parece ser '¿qué es la documentación?'. Si las 'cosas' que le interesan deben ser accesibles por reflexión, entonces su solución implícita de atributos es una solución. Pero si la intención es usar herramientas de documentación estándar para compilar documentación, entonces no es así.

La necesidad aquí mendiga la solución. ¿Cuál es la necesidad de la 'documentación'? Quizás la pregunta incorrecta?

Fuente

2012-10-01 10:10:37

Sólo para mencionar que para la mayor abundamiento, en los proyectos de pruebas que podría hacer:

[TestProperty(“Author”, “Ducky”)] 
public void SomeTest() 
{ 
     ... 
}

Usted podría ampliar este enfoque para el código regular. Prefiero no comentar sobre cuestiones teóricas. Dicho esto, tal vez se pueda crear un script que use el repositorio para extraer todos los "autores"/"editores" del archivo/clase/método específico.

Fuente

2012-10-12 12:27:27 majkinetor

El uso de atributos de Documentación en C#

Respuesta

Cuestiones relacionadas