[Python-ideas] Conventions for Python code documentation

[Guido van Rossum]

"Napoleon"?

On Mon, Jan 19, 2015 at 12:48 PM, Georg Brandl <g.brandl at gmx.net> wrote:

> On 01/19/2015 08:54 PM, Guido van Rossum wrote:
> > Unfortunately PEP 257 falls short on specifying how to describe
> arguments -- it
> > has only one example, it's not normative, and there's not much code that
> follows
> > the example. The reST conventions are more common, but the stdlib itself
> rarely
> > uses them. It would be nice to come up with a better convention that
> takes PEP
> > 484 into account (so doc generators can incorporate the argument type
> > annotations into the generated output, merged with per-argument from the
> docstring).
>
> I'll be happy to implement that.  Basically if you use
>
> :param x: description
> :type x: type
>
> you could just leave out the "type" line and have it generated from the
> annotation.
>
> I guess it's very similar for Google and numpy style docstrings, which are
> supported by the (as of 1.3 built-in) Napoleon extension.
>
> Georg
>
> _______________________________________________
> Python-ideas mailing list
> Python-ideas at python.org
> https://mail.python.org/mailman/listinfo/python-ideas
> Code of Conduct: http://python.org/psf/codeofconduct/
>



-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20150119/3c9846f9/attachment.html>