Cem Karan wrote, on Wednesday, May 17, 2017 2:48 AM > > On May 16, 2017, at 12:36 PM, rzed <rzan...@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. -- https://mail.python.org/mailman/listinfo/python-list
