From owner-freebsd-numerics@FreeBSD.ORG Tue Aug 7 20:57:43 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 5FB581065670 for ; Tue, 7 Aug 2012 20:57:43 +0000 (UTC) (envelope-from peter@rulingia.com) Received: from vps.rulingia.com (host-122-100-2-194.octopus.com.au [122.100.2.194]) by mx1.freebsd.org (Postfix) with ESMTP id C587C8FC17 for ; Tue, 7 Aug 2012 20:57:41 +0000 (UTC) Received: from server.rulingia.com (c220-239-247-45.belrs5.nsw.optusnet.com.au [220.239.247.45]) by vps.rulingia.com (8.14.5/8.14.5) with ESMTP id q77KveRu048932 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Wed, 8 Aug 2012 06:57:40 +1000 (EST) (envelope-from peter@rulingia.com) X-Bogosity: Ham, spamicity=0.000000 Received: from server.rulingia.com (localhost.rulingia.com [127.0.0.1]) by server.rulingia.com (8.14.5/8.14.5) with ESMTP id q77KvPDr010806 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Wed, 8 Aug 2012 06:57:26 +1000 (EST) (envelope-from peter@server.rulingia.com) Received: (from peter@localhost) by server.rulingia.com (8.14.5/8.14.5/Submit) id q77KvPA6010805 for freebsd-numerics@freebsd.org; Wed, 8 Aug 2012 06:57:25 +1000 (EST) (envelope-from peter) Date: Wed, 8 Aug 2012 06:57:25 +1000 From: Peter Jeremy To: freebsd-numerics@freebsd.org Message-ID: <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> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="qMm9M+Fa2AknHoGS" Content-Disposition: inline In-Reply-To: <20120805191954.GA50379@troutmask.apl.washington.edu> X-PGP-Key: http://www.rulingia.com/keys/peter.pgp User-Agent: Mutt/1.5.21 (2010-09-15) 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 20:57:43 -0000 --qMm9M+Fa2AknHoGS Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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=20 >> hope whomever commits my code will respect my style and keep the lengthy= =20 >> 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. --=20 Peter Jeremy --qMm9M+Fa2AknHoGS Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (FreeBSD) iEYEARECAAYFAlAhgTUACgkQ/opHv/APuIfeuQCfasUDBNGffA4ztejWbAEPLBCc WeAAniSA2z7iZZFlr47CYHlYonMtEvBk =4suN -----END PGP SIGNATURE----- --qMm9M+Fa2AknHoGS--