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

Mon Aug 12 17:20:13 UTC 2013

Hi Sean,

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? If so, how
would we keep that list in sync?

Cheers,

Vítor Baptista

Developer  |  http://vitorbaptista.com |
LinkedIn<http://www.linkedin.com/in/vitorbaptista>|
@vitorbaptista <http://twitter.com/vitorbaptista>

The Open Knowledge Foundation <http://okfn.org>

*Empowering through Open Knowledge*

http://okfn.org/  |  @okfn <http://twitter.com/okfn>  |  OKF on
Facebook<https://www.facebook.com/OKFNetwork> |
Blog <http://blog.okfn.org/>  |  Newsletter<http://okfn.org/about/newsletter/>

2013/8/12 Sean Hammond <sean.hammond at okfn.org>

> 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?
>
> _______________________________________________
> Services-coord mailing list
> Services-coord at lists.okfn.org
> http://lists.okfn.org/mailman/listinfo/services-coord
> Unsubscribe: http://lists.okfn.org/mailman/options/services-coord
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/ckan-dev/attachments/20130812/c90965ef/attachment-0001.html>