How should I document exceptions thrown by a method?

[Ben Finney]

Arcadio <arcadiosincero at gmail.com> writes:

> 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.

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

> 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?

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

> 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?

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.

-- 
 \         “My girlfriend has a queen sized bed; I have a court jester |
  `\   sized bed. It's red and green and has bells on it, and the ends |
_o__)                                         curl up.” —Steven Wright |
Ben Finney