Saturday, February 5, 2011

Automatically generating XML documentation for thrown exceptions in C#

In C#, it is good practice to add XML documentation to describe any exceptions that a method can throw. It is not difficult to add these for exceptions that you throw yourself. However, if I'm calling another method, and I've decided not to handle an exception thrown by this second method, there's no point in me re-writing existing documentation. I need to find the documentation for this second method and copy & paste it into the documentation for my method. Worse still are Framework methods, where I find myself copy & pasting little chunks of text from MSDN into my documentation.

Are there any tools that can automate this process? I'm thinking that there must be a plugin for VS that allows you to right-click a called method and select something like "Add Exception documentation to calling method documentation". Any suggestions would be helpful.

  • This sounds like a feature request for ghostdoc. It doesn't do this, but it does help with copying documentation when overriding a method or implementing an interface.

    That being said, such a feature would have only limited usefulness because C# does not have checked exceptions like Java.

    Andrew Hare : +1 but I disagree about checked exceptions - knowing what kind of exceptions may be thrown is helpful documentation even if you do not have checked exceptions.
    From Wim Coenen

0 comments:

Post a Comment