[Python-ideas] Conventions for Python code documentation

[Terry Reedy]

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?

 > 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?

Would type hints be added to the signatures in .rst docs?

-- 
Terry Jan Reedy