[SciPy-dev] Documenting Warnings
Fri Jun 26 17:21:52 CDT 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.
--- On Fri, 6/26/09, Pierre GM <email@example.com> wrote:
> From: Pierre GM <firstname.lastname@example.org>
> Subject: Re: [SciPy-dev] Documenting Warnings
> To: "SciPy Developers List" <email@example.com>
> 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 <firstname.lastname@example.org>
> > wrote:
> > All,
> > How do we document a warning, a note that should be
> > 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
> > :
> > .. warning::
> > Description.
> Meh. Not the best as you pointed out.
> > There is no Warnings heading in the docstring
> I've noticed that and regret it.
> > Why can't you put it either under Notes or under
> Because you may want to stress one particular aspect that
> 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
More information about the Scipy-dev