[Python-ideas] Conventions for Python code documentation
Guido van Rossum
guido at python.org
Tue Jan 20 17:31:33 CET 2015
On Mon, Jan 19, 2015 at 10:39 PM, Terry Reedy <tjreedy at udel.edu> wrote:
> On 1/19/2015 2: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.
> Because I have not seen such used, except maybe once, I have been meaning
> to ask if I am allowed to use rst markup in stdlib docstrings?
I prefer you don't use them. We don't generate docs from the stdlib
sources, and if someone generated them locally they would probably be doing
themselves a disservice -- the docstrings exist for the benefit of the
help() builtin, which AFAIK doesn't understand rst markup.
> > 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).
> My impression is that the plan is that stdlib .py files would not have
> type annotations, but that they might be in stub files. Still true?
Correct. The stdlib is a special flower in so many ways... (Stubs are also
useful for 3rd party libraries that haven't been updated yet.)
> Would type hints be added to the signatures in .rst docs?
I think you and Georg may have to decide what to do.
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Python-ideas