classification
Title: Decimal documentation lists "first" and "second" arguments, should be "self" and "other"
Type: Stage: needs patch
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: adam.woodbeck, docs@python, eric.smith, ezio.melotti, francismb, mark.dickinson, rhettinger, terry.reedy
Priority: low Keywords: easy, patch

Created on 2011-05-26 11:59 by eric.smith, last changed 2011-10-19 20:49 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
issue_12185.patch francismb, 2011-06-03 14:30 review
issue_12185-ajw.patch adam.woodbeck, 2011-06-03 14:58 Patch to decimal.rst review
Messages (13)
msg136947 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2011-05-26 11:59
http://docs.python.org/library/decimal.html

In 9.4.2, "Decimal objects", some of the methods mention the first and second parameters, when really it should be "self" and the argument, usually named "other" and sometimes something more specific. These include:

compare_total
copy_sign
next_toward
quantize (argument is exp)
rotate
scaleb
shift

It looks this is left over from where the same-named functions are described in the "Context objects" section.
msg137126 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-05-28 12:16
Note that usually 'self' is not included in the arguments of methods.  The 3.3 doc correctly uses e.g. copy_sign(other).  A 'd.' could also be added so that the end result looks like:
  d.copy_sign(other)
but it's not mandatory (if done, all the other methods should be updated as well).
msg137136 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2011-05-28 14:39
I'm not talking about the method itself but rather the descriptive text. For example:

copy_sign(other)

    Return a copy of the first operand with the sign set to be the same as the sign of the second operand. 

There is no second operand, unless you consider "self" the first and "other" the second. Which of course is true inside the method, but it reads oddly as a description of the method from the outside.
msg137156 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-05-28 22:06
Return a copy of *self* with the sign set to be the same as the sign of *other*.

seems clearer to me.
msg137163 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-05-29 01:44
In this case using:
   d.copy_sign(other)
and then refer to 'd' and 'other' might be clearer.
msg137183 - (view) Author: Adam Woodbeck (adam.woodbeck) * Date: 2011-05-29 12:57
I propose:

object.copy_sign(other)

    Return a copy of *object* with the sign set to be the same as the sign of *other*.

This format is most familiar to me.  But like Ezio wrote, all other methods referring to first and second operands would need to updated to refer to *object* and *other*, respectively.
msg137185 - (view) Author: Adam Woodbeck (adam.woodbeck) * Date: 2011-05-29 13:43
Or rather:

object.copy_sign(other)

    Return a copy of *object* with the sign set to be that of *other*.
msg137187 - (view) Author: Adam Woodbeck (adam.woodbeck) * Date: 2011-05-29 14:58
Sorry guys.  I'm new at this.  After reviewing this thread, Terry's suggestion makes the most sense to me.
msg137520 - (view) Author: Francis MB (francismb) * Date: 2011-06-03 14:30
Hi all,
that is my first contribution. Please let me know if all it's OK.

Thanks in advance !
msg137521 - (view) Author: Adam Woodbeck (adam.woodbeck) * Date: 2011-06-03 14:58
Hi Francisco,

I finally found time to create a patch for this issue.  I was just saving the patch I wrote as your update arrived in my inbox.  I've included my patch for good measure.  It's better to have two proposed patches than none at all in my opinion.

Adam
msg137534 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-06-03 15:48
I'm not sure this improves the docs.  Will give it more thought and thorough review at a later date.  Also, I will compare it to the "docstrings" in the spec itself.
msg137635 - (view) Author: Francis MB (francismb) * Date: 2011-06-04 11:31
Hi Adam,
I couldn’t see that from the threat context, I'm new to this and just
wanted to learn the work flow and tools so I've just picked up an
easy issue to start with. Anyway your patch seems more complete.
msg145962 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-10-19 20:49
Sorry, I'm going to reject this one.  I applied the patch and looked at the generated docs, finding them to be less readable than before.  AFAICT, we've had no issues with people mis-reading the text as currently presented.   Also, I looked back at the underlying spec, http://speleotrove.com/decimal/daops.html , and found that it tended to refer to first and second operand.  I would like to keep our docs as close to that as possible.
History
Date User Action Args
2011-10-19 20:49:00rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg145962
2011-06-04 14:47:35mark.dickinsonsetnosy: + mark.dickinson
2011-06-04 11:31:37francismbsetmessages: + msg137635
2011-06-03 15:48:43rhettingersetpriority: normal -> low

messages: + msg137534
2011-06-03 14:58:54adam.woodbecksetfiles: + issue_12185-ajw.patch

messages: + msg137521
2011-06-03 14:30:29francismbsetfiles: + issue_12185.patch

nosy: + francismb
messages: + msg137520

keywords: + patch
2011-05-29 14:58:04adam.woodbecksetmessages: + msg137187
2011-05-29 13:43:03adam.woodbecksetmessages: + msg137185
2011-05-29 12:57:00adam.woodbecksetmessages: + msg137183
2011-05-29 01:44:40ezio.melottisetmessages: + msg137163
2011-05-28 22:06:17terry.reedysetnosy: + terry.reedy
messages: + msg137156
2011-05-28 17:05:21rhettingersetassignee: docs@python -> rhettinger

nosy: + rhettinger
2011-05-28 14:39:20eric.smithsetmessages: + msg137136
2011-05-28 12:48:40adam.woodbecksetnosy: + adam.woodbeck
2011-05-28 12:16:06ezio.melottisetnosy: + ezio.melotti
messages: + msg137126

keywords: + easy
stage: needs patch
2011-05-26 11:59:22eric.smithcreate