NX: questions about javadoc, HELP!

[ZhiYuan Lin]

Why my @param is unuseful??? in the doc of my class, all the methods have not the
Parameters:
............. why??
just have Returns:.... and Throws: ....
my commands is:
javadoc -d docs\javadoc *.java
the another question is: should i to use the commands paramter -private? if no, all my private innter class will can't show.

[Andrew Monkhouse]

Hi ZhiYuan
Would you care to post one example of your comments where the JavaDoc has not done what you expect it to do? Along with the method signature.
Regards, Andrew

[ZhiYuan Lin]

hi andrew:
for example

   /**
    * Creates a new record in the database. it locks the entire database 
    * during the creating.
*
* @param String[] data - The values of record to create.It is
    * must have exactly the same number of elements as the field count
    * of the database schema. 
* @return long - The record number of the new record.
* @exception DuplicateKeyException - If attempted to add a duplicate key.
* The first field, the key, must be unique in the database.
* @exception DataSystemException - If database file could not be
    * accessed with an I/O error occuring or if another thread 
    * has interrupted the current thread.And if the wrong number of
    *     fields was provided by the parameter.
*/
    public synchronized long createRecord(String [] data)
    throws DuplicateKeyException {
//.......................
 

In the doc of this method is:
createRecord
public long createRecord(java.lang.String[] data)
throws DuplicateKeyExceptionCreates a new record in the database. it locks the entire database during the creating.
Specified by:
createRecord in interface DBAccess
Returns:
long - The record number of the new record.
Throws:
DuplicateKeyException - - If attempted to add a duplicate key. The first field, the key, must be unique in the database.
DataSystemException - - If database file could not be accessed with an I/O error occuring or if another thread has interrupted the current thread.And if the wrong number of fields was provided by the parameter.

???

[ZhiYuan Lin]

O
* @param String[] data
----error
the String[] is superabundance and make error

all my method must modify !!!

what about the other question? should i uses the -private?

[Andrew Monkhouse]

Hi ZhiYuan
You should not be specifying the type of your input parameter.
Try the following, you should see that it will work.

/**
    * Creates a new record in the database. it locks the entire database
    * during the creating.
*
* @param data - The values of record to create.It is
    * must have exactly the same number of elements as the field count
    * of the database schema.
* @return long - The record number of the new record.
* @exception DuplicateKeyException - If attempted to add a duplicate key.
* The first field, the key, must be unique in the database.
* @exception DataSystemException - If database file could not be
    * accessed with an I/O error occuring or if another thread
    * has interrupted the current thread.And if the wrong number of
    *     fields was provided by the parameter.
*/
    public synchronized long createRecord(String [] data)
    throws DuplicateKeyException {

Regards, Andrew

[Andrew Monkhouse]

Hi ZhiYuan
I created the documentation for all methods and variables, no matter what their scope was.
However I did not run javadoc with the -private option.
So the comments were in my code, but not in the provided API documentation.
Regards, Andrew

[Andrew Monkhouse]

Hi ZhiYuan
Some more thoughts for you....
In the comment for the parameter "data", you should have a space between the fullstop following "create" and the next sentence "It is...". Without that space, both sentences will appear in the summary.
Your exception sentence should not have a dash "-" in it. Javadoc will create it's own dash. If you look at the documentation you will see two dashes.
By the way, the tag "@exception" and "@throws" are identical. So you can use whichever you prefer. Some people prefer to say "@throws exception" just because it sounds more like what happens.
Regards, Andrew

[ZhiYuan Lin]

thanks for your advice
can you reply my the other question?
and
DataSystemException that extends RuntimeException, should write in the comments doc?

[Andrew Monkhouse]

Hi ZhiYuan
I described how I handled private methods and variables above.
Yes, I think if you decided you needed to create an exception, you should be describing it. Especially when it extends RuntimeException - you need to describe why you decided that you needed it, what alternatives you considered, and why you extended RuntimeExtension.
Regards, Andrew