Survey: improving the Python std lib docs

[Ned Batchelder]

On Wednesday, May 17, 2017 at 5:48:30 AM UTC-4, Cem Karan wrote:
> 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.


Can you give an example of such a method? Often, that signature is used
because there is no pre-conception of what the arguments might be.

--Ned.