From owner-freebsd-numerics@FreeBSD.ORG Tue Aug 7 21:19:21 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 925A6106564A for ; Tue, 7 Aug 2012 21:19:21 +0000 (UTC) (envelope-from sgk@troutmask.apl.washington.edu) Received: from troutmask.apl.washington.edu (troutmask.apl.washington.edu [128.95.76.21]) by mx1.freebsd.org (Postfix) with ESMTP id 4C7D28FC17 for ; Tue, 7 Aug 2012 21:19:21 +0000 (UTC) Received: from troutmask.apl.washington.edu (localhost.apl.washington.edu [127.0.0.1]) by troutmask.apl.washington.edu (8.14.5/8.14.5) with ESMTP id q77LJExI061807; Tue, 7 Aug 2012 14:19:14 -0700 (PDT) (envelope-from sgk@troutmask.apl.washington.edu) Received: (from sgk@localhost) by troutmask.apl.washington.edu (8.14.5/8.14.5/Submit) id q77LJEg0061806; Tue, 7 Aug 2012 14:19:14 -0700 (PDT) (envelope-from sgk) Date: Tue, 7 Aug 2012 14:19:14 -0700 From: Steve Kargl To: Peter Jeremy Message-ID: <20120807211914.GA58818@troutmask.apl.washington.edu> 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 Content-Disposition: inline In-Reply-To: <20120807205725.GA10572@server.rulingia.com> User-Agent: Mutt/1.4.2.3i 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: Tue, 07 Aug 2012 21:19:21 -0000 On Wed, Aug 08, 2012 at 06:57:25AM +1000, 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. There can be 2 man pages. One that provides the user with the usual information you outline above (e.g., casin.3), and one that provides implementation details (e.g. casin.7). OTOH, I'm just happy someone else is taking up the task(s) of implementing missing C99 libm functionality. -- Steve