2009/6/26 Pierre GM <pgmdevlist@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