Complex arg-trig functions

[Stephen Montgomery-Smith]

On 08/07/2012 03:57 PM, Peter Jeremy wrote:
> 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.
>

I completely agree.  I followed this philosophy in my code.