Complex arg-trig functions

[Peter Jeremy]

On 2012-Aug-05 12:19:54 -0700, Steve Kargl <sgk at troutmask.apl.washington.edu> wrote:
>On Sun, Aug 05, 2012 at 01:48:53PM -0500, Stephen Montgomery-Smith wrote:
>> I plan to respect your style (keep out very lengthy comments), but I 
>> hope whomever commits my code will respect my style and keep the lengthy 
>> comments.
>
>Essay long comments probably belong in the man page if the essay is
>important to the details of implementation.  Bruce may disagree with
>me.

I also believe that implementation details belong in the code and not
the man page.  The man page should contain information necessary to
use the function: Domain, range, behaviour with exceptional inputs,
accuracy and similar.  Any "unexpected" behaviours as a side-effect of
the implementation can be mentioned under BUGS.  The user shouldn't
need to know that it's implemented by range-reduction to [0 .. e/7]
and then evaluated with an 11th order truncated Chebyshev polynomial
that's had coefficients tweaked by a demon I summoned one evening.

OTOH, the code itself should contain comments explaining what it is
doing - particularly where it is relying on details of the floating
point implementation or the difference between an operation on real
(or complex) numbers and the same operation on float/double/...
numbers.  It's also useful to document why alternative (particularly
"obviously better" alternative) approaches won't work.

-- 
Peter Jeremy
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 196 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/freebsd-numerics/attachments/20120807/fa53198d/attachment.pgp