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

[Sean Hammond]

> So, how would the documentation for a function available to an extension
> would be? It would have a :raises: part for every exception that it raises,
> plus every exception that the methods it calls raises as well?

Yep

> If so, how would we keep that list in sync?

Whenever you add or remove an exception from a method or function, you
would have to grep the source code for anyone using that function and
update their docstrings.

Also if you change a function so that it calls a new function (or
potentially calls a function it was already calling, but with different
params) then you need to check the function you're calling's docstring
to check whether you need to update your own function's docstring.

I know it sounds pretty bad, but raising exceptions can make CKAN crash
so I don't think I mind being quite strict about them.

I think Joe is onto something in his reply though, the way to keep the
needed docstring-updating under control may be to reduce how often our
functions throw exceptions and reduce the number of different types of
exceptions that get thrown, including by catching exceptions and
potentially wrapping them in other exceptions and re-raising, that sort
of thing.

So for example all CKAN validator functions should raise
ckan.logic.Invalid and never any other exception, auth functions should
raise NotAuthorized, action functions may have a few different
ckan.logic.* exceptions, but the general idea is it shouldn't just be
that any function anywhere in CKAN might raise any random type of
exception (whether the exception is listed in its docstring or not).