[SciPy-dev] Documenting Warnings
Fri Jun 26 16:03:08 CDT 2009
On Jun 26, 2009, at 4:48 PM, Ralf Gommers wrote:
> On Fri, Jun 26, 2009 at 3:24 PM, Pierre GM <firstname.lastname@example.org>
> 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 ?
> For longer reST doc files you can use (see for example http://docs.scipy.org/numpy/docs/numpy-docs/user/index.rst/)
> .. warning::
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
[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 ?
More information about the Scipy-dev