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.

Do you want to propose a patch?
https://docs.python.org/3/library/math.html#hyperbolic-functions should be updated as well.

How about simply 'inverse hyperbolic cosine', etc.  I think that's more likely to be immediately obvious to readers.

and the 'radians' bit is obviously nonsense.

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>
> _______________________________________
>

Here's a patch.

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?

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>
> _______________________________________
>

Kevin: does the attached patch look okay to you?

Updated patch, fixing an accidental double space in the previous one.

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

Mark: The patch looks good.  Thanks!

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

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

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

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

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.

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

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

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

Closing as fixed.