Survey: improving the Python std lib docs

[Deborah Swanson]

Cem Karan wrote, on Wednesday, May 17, 2017 2:48 AM
> 
> 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

I'd also like to see all of the above, especially what the possible
*args or **kwargs are.

Sure hope someone who might do these things is reading this.