Documenting libm function errors

["Joseph S. Myers" <joseph at codesourcery dot com>]

[Including libc-alpha on discussion starting on the gcc list.]

On Fri, 10 Feb 2012, James Courtier-Dutton wrote:

> I think a starting point would be at least documenting correctly the
> accuracy of the current libm, because what is currently in the
> documents is obviously wrong.

To the extent that there is documentation I think some of it is 
automatically generated from the ULPs files in the glibc testsuite 
(manual/libm-err-tab.pl).  Apart from the limited information that can be 
conveyed by a single number if accuracy varies over the domain of the 
function, it's also likely that functions may have a theoretical 
justification that gives error bounds that can be relied upon more than 
the ones in the ULPs files.  Also, libm-err-tab.pl hardcodes a list of 
platforms - it would be better for each platform's name for the manual to 
go somewhere in its sysdeps directory - and it also seems unfortunate for 
the output generated to depend on whether or not the ports add-on is 
present (although I don't see a good way to avoid that with this 
approach).

> It certainly does not document that sin() is currently more accurate
> than sinl() on x86_64 platforms, even with -O0.
> I think the documentation should be along the lines of for
> Function name: sin(x)
> -pi/2 < x < pi/2, accuracy is +-N
> pi/2 < x < large number, accuracy is +-N
> large number < x < max_float, accuracy is +-N
> If a performance figure could also be added, so much the better. We
> could then know that implementation 1 is quicker than implementation 2
> and the programmer can do the trade offs.

That sort of thing would make sense - though it would be a lot of work to 
add for existing functions.

-- 
Joseph S. Myers
joseph@codesourcery.com