Survey: improving the Python std lib docs

[Cem Karan]

On May 16, 2017, at 12:36 PM, rzed <rzantow at gmail.com> wrote:

> On Friday, May 12, 2017 at 6:02:58 AM UTC-4, Steve D'Aprano wrote:
>> One of the more controversial aspects of the Python ecosystem is the Python
>> docs. Some people love them, and some people hate them and describe them as
>> horrible.
>> 
> [...]
> 
> One thing I would love to see in any function or class docs is a few example invocations, preferably non-trivial. If I need to see more, I can read the entire doc, but most times I just want a refresher on how the function is called. Does it use keywords? Are there required nameless parameters? In what order? A line or two would immediately clarify that most of the time. 
> 
> Apart from that, links to docs for uncommon functions (or to the docs of the module, if there are many) would be at least somewhat useful.

I'd like to see complete signatures in the docstrings, so when I use help() on something that has *args or **kwargs I can see what the arguments actually are.

Thanks,
Cem Karan