db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From John Embretsen <John.Embret...@Sun.COM>
Subject Re: [jira] Commented: (DERBY-1137) Implement the new method introduced in CommonDataSource for Embedded Driver
Date Fri, 24 Mar 2006 08:25:04 GMT
Daniel John Debrunner (JIRA) wrote:

>     [ http://issues.apache.org/jira/browse/DERBY-1137?page=comments#action_12371655 ]

> 
> Daniel John Debrunner commented on DERBY-1137:
> ----------------------------------------------

<snip>

> 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

Mime
View raw message