From owner-freebsd-numerics@FreeBSD.ORG Tue Aug 7 23:45:12 2012 Return-Path: Delivered-To: freebsd-numerics@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id A8D481065672 for ; Tue, 7 Aug 2012 23:45:12 +0000 (UTC) (envelope-from stephen@missouri.edu) Received: from wilberforce.math.missouri.edu (wilberforce.math.missouri.edu [128.206.184.213]) by mx1.freebsd.org (Postfix) with ESMTP id 6C5FB8FC15 for ; Tue, 7 Aug 2012 23:45:12 +0000 (UTC) Received: from [127.0.0.1] (wilberforce.math.missouri.edu [128.206.184.213]) by wilberforce.math.missouri.edu (8.14.5/8.14.5) with ESMTP id q77NMuKQ016617 for ; Tue, 7 Aug 2012 18:22:57 -0500 (CDT) (envelope-from stephen@missouri.edu) Message-ID: <5021A350.40608@missouri.edu> Date: Tue, 07 Aug 2012 18:22:56 -0500 From: Stephen Montgomery-Smith User-Agent: Mozilla/5.0 (X11; Linux i686; rv:14.0) Gecko/20120714 Thunderbird/14.0 MIME-Version: 1.0 To: freebsd-numerics@freebsd.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> In-Reply-To: <20120807205725.GA10572@server.rulingia.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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: Tue, 07 Aug 2012 23:45:12 -0000 On 08/07/2012 03:57 PM, 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. > > 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.