Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Javadoc doubt!!

 
Hari Vignesh Padmanaban
Ranch Hand
Posts: 578
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hello ranchers,
I am trying to go thro javadoc conventions. I was practicing some sample programs by wriiting them in eclipse. I have the checkstyle for Sunchecks enabled and this allows me to make sure that I follow the coding conventions followed by sun !!!
But I have a problem with the following code.

Upon saving , I get an error that says
"Expected @throws tag for RemoteException"
But, I have declared the throws tag.
am i doing something wrong ? Is tehre an convention for doing it?
Is it becos this is an interface ?
I tried to see some examples fom teh web ..and as far as i could see, i am not able to figure what is wrong ?
any idea what is wrong ?
thanks
hari
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Hari,
Here's my guess. Javadoc treats the first sentence of a javadoc comment in a special way. The first sentence is used whenever javadoc wants to just show a summary of the comment instead of the full comment. However, this implies that javadoc has got to be able to tell which is the first sentence. So in your example:

It finds "This method returns the services provided by the server", but it doesn't see end of sentence punctuation (period, question mark, eclamation mark) so it keeps on going looking for the end of your first sentence. Well, your first sentence ends up including the entire javadoc comment including the @throws RemoteException. So the style checker is going to complain that it never sees the @throws RemoteException, because in fact, it never got the chance to see it because it was swallowed up in your first sentence.
So, end the first sentence with a period and you'll be OK. I take it a step further and always leave a blank line after the first sentence to remind myself that in javadoc summary situations the first sentence is going to have to stand alone. For example,
 
Hari Vignesh Padmanaban
Ranch Hand
Posts: 578
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I still dont get it !!
I was just seeing through some sample code and logically everything seems to be right !!!
I am wondering if it has got to do anything with eclipse ?
any ideas ?
thanks
 
Hari Vignesh Padmanaban
Ranch Hand
Posts: 578
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi george,
sorry for the previous posting !! i was posting it the same time you were posting it I guess !!!
well, i refreshed and saw your posting
let me check it and get back
thanks
hari
 
Hari Vignesh Padmanaban
Ranch Hand
Posts: 578
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi george,
It still dosnt work .
well, even during teh last time, I figure it was not due to the "." as it was able to recognize the @return tag. I got an similar error for that, which was removed after I inserted the @return tag.
But i am stull not getting the reason for it show an error for @throws tag.
I also tried putting a "." at the end of the @return tag description.
But it dosent work !!!
wondering what the reason would be ?
thanks
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hari,
OK two more ideas, hope one of them works:
1) I think you have to say something about what it means when the exception is thrown (well, at least you have to say something...):

2) Do you get the same error if you use the @exception rather than the @throws Javadoc tag?
 
Hari Vignesh Padmanaban
Ranch Hand
Posts: 578
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi george ,


works
even though, I am really suprised at why it should be like that?
O tried changing it to exception..that wodunt work
and also if I have an int called a in my method
Then I have to start the param tag with the name "a" and then follow it by some description !!!
like
@param a an int for storing the age
Is SUN so strict on dicumentation ? or is it just eclipse ?
anyways, thanks george for solving teh problem. I have seen siting with it for 1.5 hrs
Sure that these would help when I start writting teh real project
[ March 18, 2004: Message edited by: Hari Vignesh Padmanaban ]
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Hari,
Actually I think it's kind of cool that it makes you enter some explanatory text after saying that a method throws an exception. Wouldn't you be curious about why the exception could be thrown?
Also, it's cool that the style checker caught you using "a" as a parmaeter name.
Wouldn't "age" be a much better name for this parameter?
Doesn't "age" convey a lot more information than "a"?
Glad you got it working.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic