Personally, I think under Notes - with suitable emphasis, e.g., bracketed w/ double *'s, i.e., **Warning:** - would suffice. However, if it did exist in the standard and was removed, perhaps a summary of why could be added to the FAQ. DG --- On Fri, 6/26/09, Pierre GM <pgmdevlist@gmail.com> wrote:
From: Pierre GM <pgmdevlist@gmail.com> Subject: Re: [SciPy-dev] Documenting Warnings To: "SciPy Developers List" <scipy-dev@scipy.org> Date: Friday, June 26, 2009, 2:03 PM
On Jun 26, 2009, at 4:48 PM, Ralf Gommers wrote:
On Fri, Jun 26, 2009 at 3:24 PM, Pierre GM <pgmdevlist@gmail.com>
wrote: All, How do we document a warning, a note that should be displayed differently as a note ? Don't we have a "Warnings" entry in the docstrings standard ? Thx
For longer reST doc files you can use (see for example http://docs.scipy.org/numpy/docs/numpy-docs/user/index.rst/)
:
.. warning::
Description.
Meh. Not the best as you pointed out.
There is no Warnings heading in the docstring standard.
I've noticed that and regret it.
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).
And special reST markup like the above is discouraged in docstrings because it looks bad on text terminals.
So why don't we have a Warning entry in the docsring standard ? Pauli, what are your thoughts about that ? I know for a fact that it'd be quite easy to implement. Any strong reason against that ?
_______________________________________________ Scipy-dev mailing list Scipy-dev@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev