How should I document exceptions thrown by a method?

[Arcadio]

I use Doxygen to document my source code, and I'm wondering how
exceptions thrown by a method of a class should be documented in the
following example.

I have a Settings class that is used to hold application settings. A
Settings object initializes itself from a ConfigParser that gets
passed in as an argument to the constructor. If a setting isn't found
in whatever the ConfigParser is reading settings from, the
ConfigParser's get() method will raise an exception. Should I just
say that clients of my Settings class should be prepared to catch
exceptions thrown by ConfigParser? Do I even have to mention that as
it might be just implied? Or should Setting's constructor catch any
exceptions raised by the ConfigParser and "convert it" to a Settings-
specific exception class that I then document?

 

[Chris Torek]

So the caller is aware of, and takes responsibility for, the
ConfigParser instance.

In this case IMO it is implied that one might get exceptions from the
object one passes as an argument to a callable.

Yes. But on the other hand:
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
...



I would suggest that in this case, too, "explicit is better than
implicit": the documentation should say "will invoke x.get() and
therefore propagate any exception that x.get() might raise".

Please, no. Since the ConfigParser object was created and passed in by
the calling code, the calling code needs to know about the exceptions
from that object.

In *some* cases (probably not applicable here), one finds a good
reason to transform one exception to another. In this case I agree
with Ben Finney though, and so does "import this":

...
Simple is better than complex.
...

Letting exceptions flow upward unchanged is (usually) simpler,
hence "better".