[Issue 23677] New: log1p Documentation Doesn't Match Implementation

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=23677

          Issue ID: 23677
           Summary: log1p Documentation Doesn't Match Implementation
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: phobos
          Assignee: nobody at puremagic.com
          Reporter: john.michael.hall at gmail.com

`std.math.exponential.log1p`'s documentation says that it is 1) more accurate
for small values of x and 2) that it is a conversation of the CEPHES library.

1) It is only more accurate if a) INLINE_YL2X is true (which is likely only
using the hard-ware implementation on DMD), and b) you are using either reals
or it is ctfe. If neither of these are true, then the function is basically
calling log(1+x), so there is no improvement in accuracy (so for floats and
doubles without CTFE, it is not any different). 

2) The CEPHES library has an implementation of log1p [1] using doubles that
uses a Taylor expansion. The version here is not using it. The only thing it
has similar is the check for a value near to 1 and special casing it and even
then the special casing is different. 

I would recommend bringing the documentation in line with the implementation by
describing the accuracy of the function more accurately and removing the
references to CEPHES for this one.

[1] https://github.com/jeremybarnes/cephes/blob/master/cprob/unity.c

--