[SciPy-dev] Documenting Warnings

[David Goldsmith]

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
>