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.

[rhettinger]

Lisa is not a committer. The assignment means that she is working on the patch. BTW, the decimal package has long been my area as well (writing a C implementation does not give you exclusive decision making over the docstrings.)

[lisroach]

Hi Stefan and Raymond,

Here's my start on the patch, I wanted to get your opinions on the direction before I go too far.

I've been comparing the two sets of docstrings, and trying to synchronize them in the clearest way that most closely matches the decimal specification docs.

Let me know what you think!

[lisroach]

I just noticed some trailing whitespace in the patch, ignore them for now and they'll be removed in the next patch.

[lisroach]

Anyone get the chance to look over this yet?

[skrah]

Raymond: "code area" meant literally that -- all code under Modules/_decimal/* is by myself.

It is well understood that you and many people (e.g. Mark Dickinson)
have a stake in Decimal. This however does not warrant reassigning
an issue in which I had already indicated to be cooperative.

I want to know what is going into that code area.

Lisa: I think I can take a look in the weekend.

[skrah]

Lisa, thanks for the patch. I've left some comments -- some docstrings in the Python version are outdated, some not quite correct, some are not very clear (to me).

I don't know how to proceed. Initially I thought it would be as easy as just taking over all Python docstrings verbatim, but looks like there's more work involved.

[lisroach]

Thanks for taking a look Stefan! I agree, it is definitely not as easy as it sounds.

Your review and comments are helpful, I will make adjustments to the docstrings.

If you want, I can continue to try to sync-up the docstrings and submit them for you and Raymond to review? I've been checking the docstrings against the general decimal specification: http://speleotrove.com/decimal/decarith.html, and with additional eyes on readability and best practices hopefully we can write updated, synchronized docstrings.

[skrah]

Okay great. I think it's probably best to produce an initial patch with the verbatim Python docstrings (you can of course address the comments that I already made), then we mark the passages that are clearly not valid for _decimal or outdated for _pydecimal, then we go for extra clarity.

[lisroach]

This (should) be the patch with the python docstrings copied over to the C version.

[furkanonder]

Patches are prepared but not continued. It can be merge by small additions to the patches.

[rhettinger]

One way to do is to dynamically update the docstrings on import. Something like this:

for name in dir(_decimal.Decimal):
    if name.startswith('_'):
        continue
    py_method = getattr(_decimal.Decimal, name)
    py_doc = py_method.__doc__
    if py_doc is None:
        continue
    c_method = getattr(_pydecimal.Decimal, name, None)
    if c_method is None:
        continue
    c_doc = c_method.__doc__
    if c_doc is None or len(c_doc) < len(py_doc):
        c_method.__doc__ = py_doc