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

Mon Aug 12 20:23:51 UTC 2013

<pure speculation>If we end up bubbling up loads of exceptions from deep
within the code, then it might be a sign that the exceptions need to be
handled better? Does the plugin writer care about a really deep down nested
exception or can it be handled somewhere else and do they just want to know
that they've provided a bad parameter somewhere in the data_dict? It's hard
to say without going through it I guess</pure speculation>

On 12 August 2013 18:20, Vitor Baptista <vitor at vitorbaptista.com> wrote:

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