[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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.

--
resolution:  -> rejected
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Mark Dickinson]

Changes by Mark Dickinson :


--
nosy: +mark.dickinson

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Francisco Martín Brugué]

Francisco Martín Brugué  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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.

--
priority: normal -> low

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Adam Woodbeck]

Adam Woodbeck  added the comment:

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

--
Added file: http://bugs.python.org/file9/issue_12185-ajw.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Francisco Martín Brugué]

Francisco Martín Brugué  added the comment:

Hi all,
that is my first contribution. Please let me know if all it's OK.

Thanks in advance !

--
keywords: +patch
nosy: +francismb
Added file: http://bugs.python.org/file8/issue_12185.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Adam Woodbeck]

Adam Woodbeck  added the comment:

Sorry guys.  I'm new at this.  After reviewing this thread, Terry's suggestion 
makes the most sense to me.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Adam Woodbeck]

Adam Woodbeck  added the comment:

Or rather:

object.copy_sign(other)

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Adam Woodbeck]

Adam Woodbeck  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Ezio Melotti]

Ezio Melotti  added the comment:

In this case using:
   d.copy_sign(other)
and then refer to 'd' and 'other' might be clearer.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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

seems clearer to me.

--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Raymond Hettinger]

Changes by Raymond Hettinger :


--
assignee: docs@python -> rhettinger
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Eric V. Smith]

Eric V. Smith  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Adam Woodbeck]

Changes by Adam Woodbeck :


--
nosy: +adam.woodbeck

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Ezio Melotti]

Ezio Melotti  added the comment:

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).

--
keywords: +easy
nosy: +ezio.melotti
stage:  -> needs patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12185] Decimal documentation lists "first" and "second" arguments, should be "self" and "other"

[Eric V. Smith]

New submission from Eric V. Smith :

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.

--
assignee: docs@python
components: Documentation
messages: 136947
nosy: docs@python, eric.smith
priority: normal
severity: normal
status: open
title: Decimal documentation lists "first" and "second" arguments, should be 
"self" and "other"
versions: Python 2.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com