[SciPy-dev] Documenting Warnings
David Goldsmith
d_l_goldsmith at yahoo.com
Fri Jun 26 18:21:52 EDT 2009
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 at gmail.com> wrote:
> From: Pierre GM <pgmdevlist at gmail.com>
> Subject: Re: [SciPy-dev] Documenting Warnings
> To: "SciPy Developers List" <scipy-dev at 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 at 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 at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
More information about the SciPy-Dev
mailing list