Path: csiph.com!x330-a1.tempe.blueboxinc.net!newsfeed.hal-mli.net!feeder3.hal-mli.net!news.glorb.com!postnews.google.com!news2.google.com!Xl.tags.giganews.com!border1.nntp.dca.giganews.com!nntp.giganews.com!local2.nntp.dca.giganews.com!nntp.earthlink.com!news.earthlink.com.POSTED!not-for-mail NNTP-Posting-Date: Tue, 06 Sep 2011 15:38:37 -0500 Date: Tue, 06 Sep 2011 13:38:03 -0700 From: Patricia Shanahan User-Agent: Mozilla/5.0 (Windows NT 5.2; WOW64; rv:6.0.1) Gecko/20110830 Thunderbird/6.0.1 MIME-Version: 1.0 Newsgroups: comp.lang.java.programmer Subject: Re: BitSet vs BigInteger (false Android doc) References: <4e613b65$0$311$14726298@news.sunsite.dk> <_ZGdna1ucfWYH__TnZ2dnUVZ_oudnZ2d@earthlink.com> <4e655c24$0$308$14726298@news.sunsite.dk> <826a6f26-c540-4ee9-a0c6-1cf77f20d765@glegroupsg2000goo.googlegroups.com> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Message-ID: <89qdnfwsp9pQGfvTnZ2dnUVZ_qednZ2d@earthlink.com> Lines: 34 X-Usenet-Provider: http://www.giganews.com NNTP-Posting-Host: 70.230.204.158 X-Trace: sv3-bHhLXYxjc/6XI0cNVvEUHZhtgAXdz4Yhgt7R65FyWBT+GZcRg55+bQqNtmUcnb6kUvokbCMqVuJtmWX!fYXBd9Bnao3sM3MmuB363SNyTIe63fz/y3xKAlXLsBQiaP394j415teGVqichvBSPsJco7qx01/f!VSJd8EGnw1CebNf4P1wbRT4wJz64A1xZwcrR6OYRY+jOHJg= X-Abuse-and-DMCA-Info: Please be sure to forward a copy of ALL headers X-Abuse-and-DMCA-Info: Otherwise we will be unable to process your complaint properly X-Postfilter: 1.3.40 X-Original-Bytes: 3158 Xref: x330-a1.tempe.blueboxinc.net comp.lang.java.programmer:7635 On 9/6/2011 3:02 AM, Jan Burse wrote: ... > Maybe this is based on a general assumption that javadocs > are above critique. But I think javadocs can be buggy > in the same way that code can be buggy. They are just > written by someone, and it can be that this someone had > good intentions, but nevertheless something went wrong. ... There are actually two categories of documentation involved here, prescriptive standards and implementation descriptions. The prescriptive standards are inherently "right", regardless of whether or not I agree with the decisions involved, in the sense that they define Java. A BigInteger implementation whose bit operations do not follow 2's complement semantics would be wrong by definition. A Java core API implementer does not have the option of changing the documentation rather than code. The descriptive information can indeed be wrong. I've written material that went into Sun Microsystems technical documentation in other areas, not Java, and I can definitely make mistakes. However, in this case I've examined ground truth in the sense of reading the Android BigInteger implementation. It definitely uses the simple, reliable, but inefficient approach of converting to 2's complement from internal representation to do bit operations. Given that, it seems helpful of them to point out the inefficiency and advise use of BitSet instead. You may not agree with the trade-off they made, but that would not make the note false. Patricia