[Python-ideas] Conventions for Python code documentation

[Terry Reedy]

On 1/20/2015 11:31 AM, Guido van Rossum wrote:
> On Mon, Jan 19, 2015 at 10:39 PM, Terry Reedy
> <tjreedy at udel.edu

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

That's easy ;-).

>     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.)

My particular interest here is adding type information to the signature 
information already displayed in Idle calltips.  It would be nice if the 
typing module (eventually) had a function to do that. It could be used 
by help(function) also.  The point is to help people write correct calls 
in the first place, by providing easily accessed information, rather 
than wait for a checker or the runtime to find the error.

-- 
Terry Jan Reedy