• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

NX: questions about javadoc, HELP!

 
ZhiYuan Lin
Ranch Hand
Posts: 44
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Pie
Posts: 11943
212
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Ranch Hand
Posts: 44
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 44
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Pie
Posts: 11943
212
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Pie
Posts: 11943
212
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Pie
Posts: 11943
212
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 44
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Pie
Posts: 11943
212
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic