[issue27779] Sync-up docstrings in C version of the the decimal module
New submission from Raymond Hettinger: 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). ---------- assignee: docs@python components: Documentation keywords: easy messages: 272875 nosy: docs@python, rhettinger priority: normal severity: normal stage: needs patch status: open title: Sync-up docstrings in C version of the the decimal module versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Stefan Krah added the comment: 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. ---------- assignee: docs@python -> skrah nosy: +skrah _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Raymond Hettinger added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Lisa Roach added the comment: I will start working on the patch for this! Thanks for pointing me this way, Raymond. ---------- nosy: +lisroach _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Stefan Krah added the comment: "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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Changes by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: skrah -> lisroach _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Stefan Krah added the comment: Sorry, Raymond, this is my code area. I said I'll review a patch. ---------- assignee: lisroach -> skrah _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Raymond Hettinger added the comment: 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.) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Lisa Roach added the comment: 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! ---------- keywords: +patch Added file: http://bugs.python.org/file44513/docstrings.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Lisa Roach added the comment: I just noticed some trailing whitespace in the patch, ignore them for now and they'll be removed in the next patch. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Lisa Roach added the comment: Anyone get the chance to look over this yet? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Stefan Krah added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Stefan Krah added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Lisa Roach added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Stefan Krah added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Changes by Stefan Krah <stefan@bytereef.org>: ---------- keywords: -easy, patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Changes by Stefan Krah <stefan@bytereef.org>: ---------- keywords: +patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Lisa Roach added the comment: This (should) be the patch with the python docstrings copied over to the C version. ---------- Added file: http://bugs.python.org/file45728/docstrings.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________
Furkan Onder <furkanonder@protonmail.com> added the comment: Patches are prepared but not continued. It can be merge by small additions to the patches. ---------- nosy: +furkanonder _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue27779> _______________________________________
participants (4)
-
Furkan Onder -
Lisa Roach
-
Raymond Hettinger
-
Stefan Krah