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 question

 
Noe Cruchet
Greenhorn
Posts: 5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi all,
Questions on javadoc.
Can I generate also the javadoc for private member/method?
Is it a bad practice?
In some public method, I used {@link } to reference to some private member/method. Should I avoid doing this?

Writing comments took me a lot of time, nearly the same for coding.
Hoping nothing wrong.

Thanks for you help.

Noe
 
Roberto Perillo
Bartender
Posts: 2271
3
Eclipse IDE Java Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hey, my buddy.

Well, I added JavaDocs to all methods (including private ones) in the code. But I just generated the HTML files to the public and protected class members.

In some public method, I used {@link } to reference to some private member/method. Should I avoid doing this?


I would say yes. The idea of this access modifier is to hide things from everyone, and only the class itself knows how private stuff works.
 
Robert James Liguori
Author
Ranch Hand
Posts: 553
5
Java Netbeans IDE Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
'javadoc -protected [File].java' will produce Java documentation for protected and public classes and members. This is the default.

'javadoc -public [File].java' will produce Java documentation for public classes and members.

'javadoc -packabe [File].java' will produce Java documentation for package, protected and public classes and members.

'javadoc -private [File].java' will produce Java documentation for all classes and members. I agree, that for this assignment and in general, this option should not be used. Go with the default (-protected), but comment the private variables as well.
[ May 22, 2008: Message edited by: Robert Liguori ]
 
rinke hoekstra
Ranch Hand
Posts: 152
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I did the same as Roberto Perillo: javadoc for all elements, but only publish the publics/protected (and default).
 
Robert James Liguori
Author
Ranch Hand
Posts: 553
5
Java Netbeans IDE Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Just FYI...

My assignment explicitly states, "Provide javadoc documentation for all classes you write." Interpret that as you may, but make sure you check your specific requirements.

I personally am producing my Javadocs with the -private flag, to generated more complete (yet not standard) documentation.

Better *safe* than *sorry*, let me know if you disagree with my approach (and why).
[ June 06, 2008: Message edited by: Robert Liguori ]
 
Matthew Flint
Greenhorn
Posts: 14
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I've just started the URLyBird assignment...

My JavaDoc is for public and protected methods and classes only. I have two reasons for this:

1. It's what Sun do (see http://java.sun.com/javase/6/docs/api/)
2. It's what I'd expect if I was given the URLyBird application and told to integrate with it.

Any developer who uses URLyBird as a consumer/client would only have access to public/protected elements, so they should only expect JavaDoc for those elements. A developer who needs to change the *internal* *implementation* of a URLyBird class would naturally have access to the source code - and would see private comments therein.

(That's just my approach - I'm not sure there's a "wrong" answer here as long as you explain your decision in 'choices.txt')

Matthew
 
Robert James Liguori
Author
Ranch Hand
Posts: 553
5
Java Netbeans IDE Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Good logic... I may change my approach.
 
charlie cate
Greenhorn
Posts: 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
"javadoc documentation for all classes " does not equal "javadoc documentation for all methods in all classes "
 
Noe Cruchet
Greenhorn
Posts: 5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
It means that in the comments of public/protected methods, I should not use the "link" or "See" to the private methods.
Thanks a lot.

I will do the same.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic