classification
Title: Docstring of math.acosh, asinh, and atanh
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: mark.dickinson Nosy List: docs@python, ezio.melotti, kdavies4, mark.dickinson, python-dev, rhettinger, stutzbach, tim.peters
Priority: normal Keywords: easy, patch

Created on 2014-07-02 04:31 by kdavies4, last changed 2015-01-11 16:48 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
acosh_docstring.patch mark.dickinson, 2014-07-02 07:12 review
acosh_docstring_v2.patch mark.dickinson, 2014-07-02 07:46 review
TI-89.png kdavies4, 2014-07-05 03:48 Reference from TI-89 manual
Messages (21)
msg222067 - (view) Author: Kevin Davies (kdavies4) Date: 2014-07-02 04:31
The docstring of acosh should more accurately be 
"Return the area hyperbolic cosine of x."
instead of 
"Return the hyperbolic arc cosine (measured in radians) of x."
asinh and atanh should be changed similarly.  The result of these functions is not an angle but a ratio of areas.  See 
http://en.wikipedia.org/wiki/Inverse_hyperbolic_function.
msg222068 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-07-02 04:47
Do you want to propose a patch?
https://docs.python.org/3/library/math.html#hyperbolic-functions should be updated as well.
msg222072 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2014-07-02 06:24
How about simply 'inverse hyperbolic cosine', etc.  I think that's more likely to be immediately obvious to readers.
msg222073 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2014-07-02 06:26
and the 'radians' bit is obviously nonsense.
msg222076 - (view) Author: Kevin Davies (kdavies4) Date: 2014-07-02 07:10
Unfortunately I'm not currently set up with Mercurial and I'm not sure 
that it makes sense to get that going just for this.

On 07/01/2014 06:47 PM, Ezio Melotti wrote:
> Ezio Melotti added the comment:
>
> Do you want to propose a patch?
> https://docs.python.org/3/library/math.html#hyperbolic-functions should be updated as well.
>
> ----------
> assignee:  -> docs@python
> components: +Documentation
> keywords: +easy
> nosy: +docs@python, ezio.melotti, mark.dickinson, rhettinger, stutzbach
> stage:  -> needs patch
> type:  -> enhancement
> versions: +Python 2.7, Python 3.4, Python 3.5
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue21902>
> _______________________________________
>
msg222077 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2014-07-02 07:12
Here's a patch.
msg222078 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2014-07-02 07:13
Ezio:

> https://docs.python.org/3/library/math.html#hyperbolic-functions should be updated as well.

It looks fine to me.  What do you think should be changed?
msg222079 - (view) Author: Kevin Davies (kdavies4) Date: 2014-07-02 07:14
Yes, 'inverse' is probably more obvious to understand than 'area', 
although it doesn't tie into the 'a' of 'acosh', etc.

On 07/01/2014 08:24 PM, Mark Dickinson wrote:
> Mark Dickinson added the comment:
>
> How about simply 'inverse hyperbolic cosine', etc.  I think that's more likely to be immediately obvious to readers.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue21902>
> _______________________________________
>
msg222082 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2014-07-02 07:44
Kevin: does the attached patch look okay to you?
msg222083 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2014-07-02 07:46
Updated patch, fixing an accidental double space in the previous one.
msg222089 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-07-02 09:18
>> https://docs.python.org/3/library/math.html#hyperbolic-functions should be updated as well.
>
> It looks fine to me.  What do you think should be changed?

I just meant to say that the docs and the docstrings should be kept in sync (especially if they are short like in this case).  If the definition in the docs is better it could be used for the docstrings; if something gets improved in the docstring that is not already in the docs it should be added to the docs as well.  If either one is fine there's no need to update it.
msg222091 - (view) Author: Kevin Davies (kdavies4) Date: 2014-07-02 09:41
Mark: The patch looks good.  Thanks!
msg222271 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-07-04 08:13
> inverse' is probably more obvious to understand than 'area', 
> although it doesn't tie into the 'a' of 'acosh', etc.

Please don't make this gratuitous change.  The decision about whether to use "inverse" or "arc" was cast in stone when the functions were named "acosh" etc.   The documentation for C's math.h uses "arc".  The docs for my hand calculators all use the term "arc" in the description of what the keys do.  Why create unnecessary divergence?  

If you truly think users of acosh can't cope with "arc", then add a clarifying parenthetical for "inverse".  But don't make the function name "acosh" more opaque by not showing what it actually stands for.
msg222285 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2014-07-04 14:12
Raymond: I don't think it's gratuitous.  I'd be happy to replace the 'inverse' by 'area' if that's what people prefer.  But "hyperbolic arc cosine" is just plain incorrect.  (And the "in radians" bit is utterly nonsensical.)
msg222329 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-07-05 01:36
> I'd be happy to replace the 'inverse' by 'arc' 
> if that's what people prefer.

Yes, please.

> And the "in radians" bit is utterly nonsensical

Yes, again.
msg222335 - (view) Author: Kevin Davies (kdavies4) Date: 2014-07-05 04:47
I'm not sure what the resolution is (the patch was 'inverse', Mark said 
he'd be happy to use 'area', and Raymond quoted 'arc').  I didn't know 
this would be a big deal, and I'm sorry that I caused trouble.  But 
since one of the concerns was divergence, I thought I'd send some info 
on how the tools I've used describe it -- universally as 'inverse' in 
those that I found:

- Mathematica: ArcCosh[z] "gives the inverse hyperbolic cosine [...]" 
(http://reference.wolfram.com/mathematica/ref/ArcCosh.html)
- Modelica Standard Library: acosh "Inverse of cosh (area hyperbolic 
cosine)" 
(http://reference.wolfram.com/system-modeler/libraries/Modelica/Modelica_Math_acosh.html)
- Maple: arccosh, but unknown description 
(http://www.maplesoft.com/support/help/Maple/view.aspx?path=invtrig)
- MATLAB: acosh " Inverse hyperbolic cosine" 
(http://www.mathworks.com/help/matlab/ref/acosh.html)
- TI-89 calculator: cosh-1 "returns the inverse hyperbolic cosine [...]" 
(from manual)

Respectfully,
Kevin
msg222336 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2014-07-05 06:12
One more useless ;-) data point, from Macsyma:

? acosh;
 -- Function: acosh (<x>)
     - Hyperbolic Arc Cosine.

I don't like "area" - while accurate, nobody else uses it.  Gratuitous novelty is no virtue ;-)  I like "inverse" better than "arc", because it's all of accurate, common, and nearly self-evident.
msg233846 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-01-11 13:03
New changeset d81cabb39de3 by Mark Dickinson in branch '2.7':
Issue #21902: Replace incorrect 'hyperbolic arc sine' (etc.) with 'inverse hyperbolic sine' (etc.).  Remove meaningless reference to radians.
https://hg.python.org/cpython/rev/d81cabb39de3
msg233848 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-01-11 13:23
New changeset 5edfc6c929f9 by Mark Dickinson in branch '3.4':
Issue #21902: Replace incorrect 'hyperbolic arc sine' (etc.) with 'inverse hyperbolic sine' (etc.).  Remove meaningless reference to radians.
https://hg.python.org/cpython/rev/5edfc6c929f9
msg233850 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2015-01-11 13:28
Roundup message copied from #21902 (bad issue number):

New changeset 36099a05d76a by Mark Dickinson in branch 'default':
Issue #21092: Merge from 3.4.
https://hg.python.org/cpython/rev/36099a05d76a
msg233851 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2015-01-11 13:29
Closing as fixed.
History
Date User Action Args
2015-01-11 16:48:16berker.peksagsetstage: patch review -> resolved
2015-01-11 13:29:16mark.dickinsonsetstatus: open -> closed
resolution: fixed
messages: + msg233851
2015-01-11 13:28:52mark.dickinsonsetmessages: + msg233850
2015-01-11 13:23:42python-devsetmessages: + msg233848
2015-01-11 13:03:59python-devsetnosy: + python-dev
messages: + msg233846
2014-07-05 06:12:27tim.peterssetnosy: + tim.peters
messages: + msg222336
2014-07-05 04:47:54kdavies4setmessages: + msg222335
2014-07-05 03:48:12kdavies4setfiles: + TI-89.png
2014-07-05 01:36:03rhettingersetmessages: + msg222329
2014-07-04 14:12:07mark.dickinsonsetmessages: + msg222285
2014-07-04 08:13:39rhettingersetmessages: + msg222271
2014-07-02 09:41:28kdavies4setmessages: + msg222091
2014-07-02 09:18:25ezio.melottisetmessages: + msg222089
2014-07-02 07:53:33mark.dickinsonsettype: enhancement -> behavior
stage: needs patch -> patch review
2014-07-02 07:46:40mark.dickinsonsetfiles: + acosh_docstring_v2.patch

messages: + msg222083
2014-07-02 07:44:24mark.dickinsonsetmessages: + msg222082
2014-07-02 07:16:13mark.dickinsonsetassignee: docs@python -> mark.dickinson
2014-07-02 07:14:23kdavies4setmessages: + msg222079
2014-07-02 07:13:09mark.dickinsonsetmessages: + msg222078
2014-07-02 07:12:22mark.dickinsonsetfiles: + acosh_docstring.patch
keywords: + patch
messages: + msg222077
2014-07-02 07:10:47kdavies4setmessages: + msg222076
2014-07-02 06:26:14mark.dickinsonsetmessages: + msg222073
2014-07-02 06:24:38mark.dickinsonsetmessages: + msg222072
2014-07-02 04:47:39ezio.melottisetassignee: docs@python
type: enhancement
components: + Documentation
versions: + Python 2.7, Python 3.4, Python 3.5
keywords: + easy
nosy: + stutzbach, rhettinger, ezio.melotti, mark.dickinson, docs@python

messages: + msg222068
stage: needs patch
2014-07-02 04:31:19kdavies4create