Date: Tue, 7 Aug 2012 14:19:14 -0700 From: Steve Kargl <sgk@troutmask.apl.washington.edu> To: Peter Jeremy <peter@rulingia.com> Cc: freebsd-numerics@freebsd.org Subject: Re: Complex arg-trig functions Message-ID: <20120807211914.GA58818@troutmask.apl.washington.edu> In-Reply-To: <20120807205725.GA10572@server.rulingia.com> 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>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, Aug 08, 2012 at 06:57:25AM +1000, Peter Jeremy wrote: > On 2012-Aug-05 12:19:54 -0700, Steve Kargl <sgk@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. 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20120807211914.GA58818>