studio - excepciones de auto-documento en métodos en C#/. NET

generar documentacion visual studio 2017

Question

Me gustaría alguna herramienta, preferiblemente una que se conecte a VS 2008/2010, que vaya a través de mis métodos y agregar comentarios XML sobre las posibles excepciones que pueden arrojar. No quiero que se genere el <summary> u otras etiquetas XML porque las rellenaré yo mismo, pero sería bueno que incluso con métodos private / protected pudiera ver qué excepciones podrían arrojarse. De lo contrario, me encuentro revisando los métodos y colocando todas las llamadas de método dentro de ellos para ver la lista de excepciones y luego actualizando la <exception lista de excepciones de ese método para incluirlas. Tal vez una macro VS podría hacer esto?

De esto:

private static string getConfigFilePath()
{
    return Path.Combine(Environment.CurrentDirectory, CONFIG_FILE);
}

A esto:

/// <exception cref="System.ArgumentException"/>
/// <exception cref="System.ArgumentNullException"/>
/// <exception cref="System.IO.IOException"/>
/// <exception cref="System.IO.DirectoryNotFoundException"/>
/// <exception cref="System.Security.SecurityException"/>
private static string getConfigFilePath()
{
    return Path.Combine(Environment.CurrentDirectory, CONFIG_FILE);
}

Actualización: parece que la herramienta tendría que pasar por los métodos de forma recursiva, por ejemplo, method1 llama a method2 que llama a method3 que está documentado como throwing NullReferenceException , por lo que la herramienta también documenta tanto method2 como method1 lanzando NullReferenceException . La herramienta también necesitaría eliminar duplicados, como si dos llamadas dentro de un método estuvieran documentadas como throwing DirectoryNotFoundException , el método solo haría una lista de <exception cref="System.IO.DirectoryNotFoundException"/> una vez.

Answer 1

La respuesta larga y corta es que esto no es posible. A diferencia de Java, ninguno de los lenguajes .NET requiere que las funciones informen una lista de posibles excepciones que pueden lanzarse (lo que significa que debe detectar o informar cualquier excepción que se pueda lanzar sobre las funciones que llama). Debido a esto, no hay una manera genérica de determinar una lista exhaustiva de todas las excepciones que una función podría arrojar (estoy usando la función de palabra aquí para cubrir todo lo que está escrito como una función, incluidos operadores, constructores, etc.) porque tiene ninguna garantía en cuanto a las excepciones que podría arrojar lo que una función dada podría llamar.

Si está dispuesto a limitarse, entonces es concebible que pueda escribir algo que pueda escanear MSDN para obtener el artículo apropiado para una llamada de biblioteca .NET dada y usar la lista de excepciones allí (si corresponde) para establecer recursivamente una lista de que podría ser arrojado Sin embargo, esto no cubriría ninguna biblioteca de terceros ni detectaría excepciones lanzadas por el tiempo de ejecución ( OutOfMemoryException , Exception , NullReferenceException [a menos que desee ir un paso más allá y hacer que su análisis de excepción también determine si hay alguna posibilidad de una referencia nula, pero esto también parece imposible de hacer en un sentido completamente genérico]).

Estoy bastante seguro de que esto ha sido cubierto una o dos veces por el equipo C # (me sorprendería que Eric Lippert no haya respondido una pregunta sobre esto en SO), pero estoy bastante seguro de que se redujo a esto: si bien este tipo de sistema es útil y valioso para algunas personas , ordenar su uso (y forzarlo a informar o atrapar todas las excepciones posibles) llevó a muchos try { ... } catch (Exception ex) { ... } bloques para evitar el mantenimiento, y las capturas generales y silenciosas son mucho peores (en mi humilde opinión) que una excepción no denunciada.

Answer 2

Puede alcanzar parte de sus requisitos utilizando AtomineerUtils que tiene soporte para documentar excepciones.

También puede usar GhostDoc , GhostDoc y Agent Johnson Plugin para generar excepciones. Consulte la siguiente pregunta: Cómo documentar las excepciones lanzadas en c # /. Net

Answer 3

Exception Hunter del software RedGate te llevará a mitad de camino. Puede hacer un análisis estático de su código y mostrarle qué excepciones arrojarán las líneas de código, incluidas las llamadas a .NET Framework. No escribirá la documentación XML por usted.

Pero tengo que decir que debe ser realista acerca de cuán útil sería esta herramienta ... hay una serie de excepciones que pueden ocurrir como resultado de circunstancias extremadamente inusuales, como System.OutOfMemoryException y System.ExecutionEngineException , o como resultado de un error del programador, como System.NotImplementedException . Técnicamente, todo esto es posible, pero de manera realista, intentar documentar la mayoría de ellos para cada método no vale la pena ... terminarías con cientos de líneas de comentarios para prácticamente todos los métodos de tu aplicación.

Answer 4

RedGate Exception Hunter analiza el código para una posible excepción. Tal vez podrías usar algunas de sus funcionalidades.