classification
Title: Sync-up docstrings in C version of the the decimal module
Type: Stage: needs patch
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: skrah Nosy List: docs@python, furkanonder, lisroach, rhettinger, skrah
Priority: normal Keywords: patch

Created on 2016-08-16 19:28 by rhettinger, last changed 2020-05-27 22:36 by furkanonder.

Files
File name Uploaded Description Edit
docstrings.patch lisroach, 2016-09-09 22:36 review
docstrings.patch lisroach, 2016-12-01 21:52 review
Messages (16)
msg272875 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-08-16 19:28
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).
msg272879 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2016-08-16 19:55
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.
msg272898 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-08-17 03:18
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.
msg274200 - (view) Author: Lisa Roach (lisroach) * (Python committer) Date: 2016-09-02 04:09
I will start working on the patch for this!

Thanks for pointing me this way, Raymond.
msg274221 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2016-09-02 09:51
"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.
msg274412 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2016-09-05 17:56
Sorry, Raymond, this is my code area.  I said I'll review a patch.
msg274499 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-09-06 02:27
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.)
msg275478 - (view) Author: Lisa Roach (lisroach) * (Python committer) Date: 2016-09-09 22:36
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!
msg275491 - (view) Author: Lisa Roach (lisroach) * (Python committer) Date: 2016-09-09 23:25
I just noticed some trailing whitespace in the patch, ignore them for now and they'll be removed in the next patch.
msg278816 - (view) Author: Lisa Roach (lisroach) * (Python committer) Date: 2016-10-17 16:24
Anyone get the chance to look over this yet?
msg278922 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2016-10-18 19:19
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.
msg279278 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2016-10-23 19:47
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.
msg279895 - (view) Author: Lisa Roach (lisroach) * (Python committer) Date: 2016-11-02 03:55
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.
msg279988 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2016-11-03 11:46
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.
msg282207 - (view) Author: Lisa Roach (lisroach) * (Python committer) Date: 2016-12-01 21:52
This (should) be the patch with the python docstrings copied over to the C version.
msg370144 - (view) Author: Furkan Onder (furkanonder) * Date: 2020-05-27 22:36
Patches are prepared but not continued. It can  be merge by  small additions to the patches.
History
Date User Action Args
2020-05-27 22:36:33furkanondersetnosy: + furkanonder
messages: + msg370144
2016-12-01 21:52:27lisroachsetfiles: + docstrings.patch

messages: + msg282207
2016-11-03 11:47:10skrahsetkeywords: + patch
2016-11-03 11:46:53skrahsetkeywords: - patch, easy
2016-11-03 11:46:07skrahsetmessages: + msg279988
2016-11-02 03:55:59lisroachsetmessages: + msg279895
2016-10-23 19:47:36skrahsetmessages: + msg279278
2016-10-18 19:19:11skrahsetmessages: + msg278922
2016-10-17 16:24:00lisroachsetmessages: + msg278816
2016-09-09 23:25:59lisroachsetmessages: + msg275491
2016-09-09 22:36:11lisroachsetfiles: + docstrings.patch
keywords: + patch
messages: + msg275478
2016-09-06 02:27:44rhettingersetmessages: + msg274499
2016-09-05 17:56:41skrahsetassignee: lisroach -> skrah
messages: + msg274412
2016-09-05 17:46:42rhettingersetassignee: skrah -> lisroach
2016-09-02 09:51:25skrahsetmessages: + msg274221
2016-09-02 04:09:02lisroachsetnosy: + lisroach
messages: + msg274200
2016-08-17 03:18:15rhettingersetmessages: + msg272898
2016-08-16 19:55:22skrahsetassignee: docs@python -> skrah

messages: + msg272879
nosy: + skrah
2016-08-16 19:28:55rhettingercreate