Sync-up docstrings in C version of the the decimal module

[rhettinger]

BPO	27779
Nosy	@rhettinger, @skrah, @lisroach, @furkanonder
Files	docstrings.patch docstrings.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2016-08-16.19:28:55.744>
labels = ['easy', '3.11', 'type-feature', 'docs']
title = 'Sync-up docstrings in C version of the the decimal module'
updated_at = <Date 2021-12-01.03:21:20.269>
user = 'https://github.com/rhettinger'

bugs.python.org fields:

activity = <Date 2021-12-01.03:21:20.269>
actor = 'rhettinger'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2016-08-16.19:28:55.744>
creator = 'rhettinger'
dependencies = []
files = ['44513', '45728']
hgrepos = []
issue_num = 27779
keywords = ['easy']
message_count = 17.0
messages = ['272875', '272879', '272898', '274200', '274221', '274412', '274499', '275478', '275491', '278816', '278922', '279278', '279895', '279988', '282207', '370144', '407424']
nosy_count = 5.0
nosy_names = ['rhettinger', 'skrah', 'docs@python', 'lisroach', 'furkanonder']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue27779'
versions = ['Python 3.11']

Linked PRs

• gh-71966: Sync-up docstrings in C version of the the decimal module #101350
• gh-71966: Move the module docstring from _pydecimal to decimal #117919
• [3.12] gh-71966: Move the module docstring from _pydecimal to decimal (GH-117919) #117962

[rhettinger]

The pure python version of decimal has extensive docstrings with text and explanatory examples drawn directly from the decimal arithmetic specification. Those should all be copied to the C version as well. This will improve usability for interactive use and improve help().

I would like to leave this work for one of the new aspiring core devs (perhaps Elizabeth, Lisa, or Nofar).

[skrah]

I found the docstrings a bit too verbose (the power() docstring takes up more than a page), but I'm happy to add it and review a patch.

The patch authors need to take the hand written function signatures into account.

[rhettinger]

Historically, we've kept the docstrings 100% intact between the C and Python versions, even if they are big (see heapq.__doc__) for example.

If there are differences in the "hand written" versions. I would like to have them compared on a case by case basis and resolved. Unless the C version implements something different, there should be no reason for a docstring difference. The originals are very close to the specification and to the documentation. We tried to stay true in part because there are so many niggling details that it would be hard to know without reading the spec.

[lisroach]

I will start working on the patch for this!

Thanks for pointing me this way, Raymond.

[skrah]

"hand written signatures" refers to the signatures that Argument Clinic would generate if it were used (but I don't want that).

So this is an example of a hand written signature:

"is_infinite($self, /)\n--\n\n\"

I still wonder if people wouldn't be served better with concise docstrings, but then I'm generally in favor of a Unix manual page documentation style, so perhaps there's a cultural difference.

[skrah]

Sorry, Raymond, this is my code area. I said I'll review a patch.