[ckan-dev] All methods and functions in CKAN need docstrings with :raises:

[Sean Hammond]

Hey, something I ran across while writing the new _Writing extensions_
tutorial, many functions that CKAN makes available to extensions via the
plugins toolkit (e.g. action functions, auth functions, converters and
validators...) will often raise exceptions, which will then cause the
extension and CKAN to crash (e.g. validators and converters raise things
like Invalid or NotFound, action functions can raise NotAurthorized, etc.).

So to make it possible to write plugins that don't crash, with the
plugin writer being able to work from the CKAN documentation only and
not having to know the CKAN source code itself inside-out, all functions
in the plugins toolkit need to have docstrings that use :raises: to
document all the exceptions that they raise.

But often the exception isn't raised in the function itself, but in some
other function that it calls, so the only sane way to document the
exceptions that a function raises is going to be to first document all
the functions that it calls (and the functions that they call...)

It looks to me like we need docstrings on all functions in CKAN for
this? Is this something we should start doing?