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
