From owner-freebsd-numerics@FreeBSD.ORG Wed Aug 8 17:12:22 2012 Return-Path: Delivered-To: freebsd-numerics@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 0EE37106566C for ; Wed, 8 Aug 2012 17:12:22 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail14.syd.optusnet.com.au (mail14.syd.optusnet.com.au [211.29.132.195]) by mx1.freebsd.org (Postfix) with ESMTP id 9675D8FC08 for ; Wed, 8 Aug 2012 17:12:21 +0000 (UTC) Received: from c122-106-171-246.carlnfd1.nsw.optusnet.com.au (c122-106-171-246.carlnfd1.nsw.optusnet.com.au [122.106.171.246]) by mail14.syd.optusnet.com.au (8.13.1/8.13.1) with ESMTP id q78HCI2t009761 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Thu, 9 Aug 2012 03:12:20 +1000 Date: Thu, 9 Aug 2012 03:12:18 +1000 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Peter Jeremy In-Reply-To: <20120807205725.GA10572@server.rulingia.com> Message-ID: <20120809025220.N4114@besplex.bde.org> References: <5017111E.6060003@missouri.edu> <501C361D.4010807@missouri.edu> <20120804165555.X1231@besplex.bde.org> <501D51D7.1020101@missouri.edu> <20120805030609.R3101@besplex.bde.org> <501D9C36.2040207@missouri.edu> <20120805175106.X3574@besplex.bde.org> <501EC015.3000808@missouri.edu> <20120805191954.GA50379@troutmask.apl.washington.edu> <20120807205725.GA10572@server.rulingia.com> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: freebsd-numerics@freebsd.org Subject: Re: Complex arg-trig functions X-BeenThere: freebsd-numerics@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Discussions of high quality implementation of libm functions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 08 Aug 2012 17:12:22 -0000 On Wed, 8 Aug 2012, Peter Jeremy wrote: > On 2012-Aug-05 12:19:54 -0700, Steve Kargl 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. Of course only details visible to applications belong in the man page. But I think many details belong in meta-comments in something more like a readme than in every source file. > 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. Note that FreeBSD man pages mostly have less than this, and less than even the non-Annex parts of C99, after removing some out-of date meta-info from math.3. > 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. Unless the implementation affects the user-visible behaviour. For example, on i386 trig functions are still implemented using the i387 (except in my version), so applications are exposed to the huge errors near multiples of pi/2 (starting at 1*pi/2) that are normal for the i387. A note about this would point to the right place to blame :-). > 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. That's too detailed. Almost every line depends on IEEE754 arithmetic and on this not being too broken. Many depend on the arithmetic _not_ being the same as real arithmetic. An example is almost every line in Dekker's algorithm. > It's also useful to document why alternative (particularly > "obviously better" alternative) approaches won't work. Again too detailed. On most lines I consider a couple of routine alternatives. For critical lines, I consider and try many more. Bruce