Return-Path: Delivered-To: apmail-db-derby-dev-archive@www.apache.org Received: (qmail 62601 invoked from network); 24 Mar 2006 08:25:35 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 24 Mar 2006 08:25:34 -0000 Received: (qmail 34738 invoked by uid 500); 24 Mar 2006 08:25:33 -0000 Delivered-To: apmail-db-derby-dev-archive@db.apache.org Received: (qmail 34702 invoked by uid 500); 24 Mar 2006 08:25:33 -0000 Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: Delivered-To: mailing list derby-dev@db.apache.org Received: (qmail 34692 invoked by uid 99); 24 Mar 2006 08:25:33 -0000 Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 24 Mar 2006 00:25:33 -0800 X-ASF-Spam-Status: No, hits=0.0 required=10.0 tests=UNPARSEABLE_RELAY X-Spam-Check-By: apache.org Received-SPF: pass (asf.osuosl.org: local policy) Received: from [192.18.98.36] (HELO brmea-mail-4.sun.com) (192.18.98.36) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 24 Mar 2006 00:25:32 -0800 Received: from phys-gadget-1 ([129.156.85.171]) by brmea-mail-4.sun.com (8.12.10/8.12.9) with ESMTP id k2O8PBuf026046 for ; Fri, 24 Mar 2006 01:25:11 -0700 (MST) Received: from conversion-daemon.gadget-mail1.uk.sun.com by gadget-mail1.uk.sun.com (iPlanet Messaging Server 5.2 HotFix 1.24 (built Dec 19 2003)) id <0IWM00M01HYDJP@gadget-mail1.uk.sun.com> (original mail from John.Embretsen@Sun.COM) for derby-dev@db.apache.org; Fri, 24 Mar 2006 08:25:11 +0000 (GMT) Received: from [129.159.112.236] (khepri24.Norway.Sun.COM [129.159.112.236]) by gadget-mail1.uk.sun.com (iPlanet Messaging Server 5.2 HotFix 1.24 (built Dec 19 2003)) with ESMTPA id <0IWM0005RI1SCY@gadget-mail1.uk.sun.com> for derby-dev@db.apache.org; Fri, 24 Mar 2006 08:25:11 +0000 (GMT) Date: Fri, 24 Mar 2006 09:25:04 +0100 From: John Embretsen Subject: Re: [jira] Commented: (DERBY-1137) Implement the new method introduced in CommonDataSource for Embedded Driver In-reply-to: <1366070773.1143157400761.JavaMail.jira@ajax> To: derby-dev@db.apache.org Reply-to: derby-dev@db.apache.org Message-id: <4423ACE0.20406@Sun.COM> MIME-version: 1.0 Content-type: text/plain; charset=UTF-8; format=flowed Content-transfer-encoding: 7BIT User-Agent: Thunderbird 1.5 (X11/20060113) References: <1366070773.1143157400761.JavaMail.jira@ajax> X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N Daniel John Debrunner (JIRA) wrote: > [ http://issues.apache.org/jira/browse/DERBY-1137?page=comments#action_12371655 ] > > Daniel John Debrunner commented on DERBY-1137: > ---------------------------------------------- > Minor comment on modifying javadoc comments: In EmbeddedDataSource you have this: > > + /** > + * Moved this code from EmbeddedXADatasource to > + * share the method between different versions of XADataSource > + * This method attenpts to create resource adapter to database > > The primary description for a method (or any javadoc comment) is the first sentence in the Javadoc, which means this method > will now be described as "Moved this code from EmbeddedXADatasource to > + * share the method between different versions of XADataSource ...." > which is not its function. The first sentence should be the purpose of the method, I'm not sure it's even useful having comments that it moved. Besides, I would like to stress the need to have a full stop (aka period, aka "dot") after each full sentence in JavaDocs. Otherwise, in the generated HTML, the whole thing may look like one sentence: "Moved this code from EmbeddedXADatasource to share the method between different versions of XADataSource This method attenpts to create resource adapter to database" (There is also a typo here: "attenpts" -> "attempts"). -- John