在方法自动文档中的例外C＃/。NET [英] auto-document exceptions on methods in C#/.NET

问题描述

我想了一些工具，最好是可以插入VS 2008/2010，那会经过我的方法并添加有关他们可以抛出可能的例外XML注释。我不想让<总结> 或我要产生，因为我会填补这些了自己，但它是如果连好一点的其他XML标记私人 / 保护方法，我可以看到哪些异常会被抛出。否则，我发现自己经历的方法和徘徊在其中的所有方法调用看到例外列表中，然后更新该方法的<异常列表中包含那些。也许VS宏能做到这一点。

I would like some tool, preferably one that plugs into VS 2008/2010, that will go through my methods and add XML comments about the possible exceptions they can throw. I don't want the <summary> or other XML tags to be generated for me because I'll fill those out myself, but it would be nice if even on private/protected methods I could see which exceptions could be thrown. Otherwise I find myself going through the methods and hovering on all the method calls within them to see the list of exceptions, then updating that method's <exception list to include those. Maybe a VS macro could do this?

从这个：

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

这样：

/// <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);
}

更新：好像工具将有办理方法递归，例如，方法1调用方法2这就要求method3被记录为投掷的NullReferenceException ，这样既方法2和方法1是由工具记录为也扔的NullReferenceException 。该工具还需要消除重复，就像如果一个方法中的两个电话都记录投掷 DirectoryNotFoundException ，该方法只会名单<异常CREF =System.IO.DirectoryNotFoundException/> 一次

Update: it seems like the tool would have to go through the methods recursively, e.g., method1 calls method2 which calls method3 which is documented as throwing NullReferenceException, so both method2 and method1 are documented by the tool as also throwing NullReferenceException. The tool would also need to eliminate duplicates, like if two calls within a method are documented as throwing DirectoryNotFoundException, the method would only list <exception cref="System.IO.DirectoryNotFoundException"/> once.

推荐答案

长和短。回答是，这是不可能的。不像Java中，没有任何.NET语言的要求，功能报告，可以引发（这意味着你要么赶上或报告可以在它调用的函数抛出的异常）可能的例外列表。正因为如此，有确定每个异常的一个详尽的清单，一个函数可以抛出（我用这个词功能，这里涵盖的写过什么的像一个函数，包括运营商，建设者没有通用的方法等），因为你无法保证到可能由什么给定函数可以调用抛出的异常。

The long and the short answer is that this isn't possible. Unlike Java, none of the .NET languages require that functions report a list of possible exceptions that can be thrown (which means that you either have to catch or report any exceptions that could be thrown on functions that it calls). Because of this, there's no generic way to determine an exhaustive list of every exception that a function could throw (I'm using the word function here to cover anything that's written like a function, including operators, constructors, etc.) because you have no guarantee as to the exceptions that could be thrown by what a given function might call.

如果你愿意在有限的去，那么这是可以想象的，你可以写的东西可以扫描MSDN对于给定的.NET库调用相应的文章，并使用例外列表中出现（如果有的话）递归建立什么可能被抛出的列表。这不，但是，包括任何第三方库或乘坐由运行时（ OutOfMemoryException异常， StackOverflowException ，的NullReferenceException [除非你想利用它更进了一步，让你的异常分析还确定是否存在空引用的可能性，但是这也似乎是不可能的在一个完全一般意义]）做的。

If you're willing to go in limited, then it's conceivable that you could write something that could scan MSDN for the appropriate article for a given .NET library call and use the list of exceptions there (if any) to recursively establish a list of what could possibly be thrown. This wouldn't, however, cover any third-party libraries or catch any exceptions thrown by the runtime (OutOfMemoryException, StackOverflowException, NullReferenceException [unless you want to take it a step further and have your exception analysis also determine if there is any possibility of a null reference, but this, too, seems impossible to do in a completely generic sense]).

我敢肯定，这已经被C＃团队涵盖了两个时间（我会感到惊讶，如果埃里克利珀尚未回答了这个在SO问题），但我敢肯定它归结为：虽然这种系统是有用的，有价值的对某些人的，强制其使用（并迫使你要么报或者捕获所有可能引发的异常），导致了很多尝试{...}赶上（例外前）{...} 块为了避免客房清洁和毛毯，无声的渔获量很多比未报告异常糟糕的（恕我直言）。

I'm pretty sure that this has been covered a time or two by the C# team (I'd be surprised if Eric Lippert hasn't already answered a question about this on SO), but I'm pretty certain that it boiled down to this: While this sort of system is useful and valuable to some people, mandating its use (and forcing you either to report or catch all possibly thrown exceptions) led to a lot of try { ... } catch (Exception ex) { ... } blocks in order to avoid the housekeeping, and blanket, silent catches are a lot worse (IMHO) than an unreported exception.

这篇关于在方法自动文档中的例外C＃/。NET的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！