[Python-Dev] Docstrings on builtins

[Victor Stinner]

Hi,

For Argument Clinic, have a look at
https://docs.python.org/dev/howto/clinic.html

You can also try to copy/paste code from other files using Argument
Clinic and then run "make clinic" to regenerate the generated files.

Victor

2018-06-04 23:45 GMT+02:00 Chris Barker via Python-Dev <python-dev at python.org>:
> Over on python-ideas, someone is/was proposing literals for timedeltas.
>
> I don't expect that will come to anything, but it did make me take a look at
> the docstring for datetime.timedelta. I use iPython's ? a lot for a quick
> overview of how to use a class/function.
>
> This is what I get:
>
> In [8]: timedelta?
> Init signature: timedelta(self, /, *args, **kwargs)
> Docstring:      Difference between two datetime values.
> File:           ~/miniconda2/envs/py3/lib/python3.6/datetime.py
> Type:           type
>
>
> That is, well, not so useful. I'd like to see at least the signature:
>
> datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0,
> minutes=0, hours=0, weeks=0
>
> And ideally much of the text in the docs.
>
> I've noticed similarly minimal docstrings on a number of builtin functions
> and methods.
>
> If I wanted to contribute a PR to enhance these docstrings, where would they
> go?  I've seen mention of "argument clinic", but really don't know quite
> what that is, or how it works, but it appears to be related.
>
> Anyway -- more comprehensive docstrings on buildins could really help
> Python's usability for command line usage.
>
> Thanks,
> -  Chris
>
>
>
>
> --
>
> Christopher Barker, Ph.D.
> Oceanographer
>
> Emergency Response Division
> NOAA/NOS/OR&R            (206) 526-6959   voice
> 7600 Sand Point Way NE   (206) 526-6329   fax
> Seattle, WA  98115       (206) 526-6317   main reception
>
> Chris.Barker at noaa.gov
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
> https://mail.python.org/mailman/options/python-dev/vstinner%40redhat.com
>