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

Should be add doc comments to private members?

 
Samantha O'Neill
Greenhorn
Posts: 26
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I have in fact done this as followed the example source file in the java coding conventions produced by Sun but when I run javadoc I don't see
any of my private members displyed in the resulting html.
My instructions say that I must provide javadoc for the public interface but am not sure what I should with my existing private member doc comments.
Any input much appreciated.
Many thanks Sam
 
Nige' Perkins
Greenhorn
Posts: 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The default behaviour of javadoc is to only generate documentation for classes, interfaces, and members that have protected or public scope. Use the -private option to generate documentation for everything. Other options are -package, -protected (the default) or -public. Just type javadoc with no parameters for a full list of options.
I use javadoc comments for all classes, interfaces, and members, regardless of scope - because I think its good style. Not sure what you should submit to Sun though - I suspect the default behaviour is probably most appropriate because it only details what clients of your API can get at.
Hope this helps.
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12014
220
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Sam
I also had JavaDoc comments on all private methods and variables.
For my submission, I used standard Javadoc (I did not specify '-private').
I got 100% for documentation doing this.
Regards, Andrew
 
Samantha O'Neill
Greenhorn
Posts: 26
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks guys.
In that case I will leave all my javadoc comments as they are in my code and just submit the public API for documentation.
I have also explicitly put doc comments in for each class that implements an interface rather than letting javadoc just inherit them as I think it makes an explanation of the code more readily available for any future programmer so they don't have to go to the javadoc or find the explanation in the interface. Do you think I will be penalized for this?
Many thanks Sam
 
Max Habibi
town drunk
( and author)
Sheriff
Posts: 4118
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I don't think you'll be penalized Sam, but IMO, it's good practice to document all methods, private or otherwise. It forces you to exaimine exactly what the method is doing for you, what you expect as preconditions, and what you expect as post conditions.
All best,
M
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic