This week's book giveaway is in the OCPJP forum.
We're giving away four copies of OCA/OCP Java SE 7 Programmer I & II Study Guide and have Kathy Sierra & Bert Bates on-line!
See this thread for details.
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes NX: questions about javadoc,  HELP! Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of OCA/OCP Java SE 7 Programmer I & II Study Guide this week in the OCPJP forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "NX: questions about javadoc,  HELP!" Watch "NX: questions about javadoc,  HELP!" New topic
Author

NX: questions about javadoc, HELP!

ZhiYuan Lin
Ranch Hand

Joined: Jun 30, 2003
Posts: 44
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
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11490
    
  95

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


The Sun Certified Java Developer Exam with J2SE 5: paper version from Amazon, PDF from Apress, Online reference: Books 24x7 Personal blog
ZhiYuan Lin
Ranch Hand

Joined: Jun 30, 2003
Posts: 44
hi andrew:
for example

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
Ranch Hand

Joined: Jun 30, 2003
Posts: 44
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
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11490
    
  95

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

Regards, Andrew
Andrew Monkhouse
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11490
    
  95

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
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11490
    
  95

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
Ranch Hand

Joined: Jun 30, 2003
Posts: 44
thanks for your advice
can you reply my the other question?
and
DataSystemException that extends RuntimeException, should write in the comments doc?
Andrew Monkhouse
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11490
    
  95

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
 
It is sorta covered in the JavaRanch Style Guide.
 
subject: NX: questions about javadoc, HELP!