[SciPy-dev] Documenting Warnings

[Scott Sinclair]

>2009/6/26 Pierre GM <pgmdevlist at gmail.com>:
>
>> On Jun 26, 2009, at 4:48 PM, Ralf Gommers wrote:
>
>> Why can't you put it either under Notes or under Raises?
>
> Because you may want to stress one particular aspect that would
> otherwise be easy to overlook in a Notes. Because you want to describe
> a known limitation that doesn't raise any exception (and maybe not
> even a warning per se: in that case, I'd put in the Raises section as
> you suggest).
>
> [FYI, I was just checking recent updates in the docstrings of numpy.ma
> and noticed that Pauli got rid of the Warnings section and merged it
> in a Notes. I still think that the two sections shouldn't have been
> merged, but I won't lose sleep over it. I'm just curious).

I'm also guilty of mangling your docstrings in this way, so that
they'd match the standard. Including an optional warnings section in
the standard sounds like a good idea to me..

Cheers,
Scott