• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Tim Cooke
  • Jeanne Boyarsky
  • Bear Bibeault
Sheriffs:
  • Knute Snortum
  • paul wheaton
  • Devaka Cooray
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Ron McLeod
  • Piet Souris
  • Ganesh Patekar
Bartenders:
  • Tim Holloway
  • Carey Brown
  • salvin francis

Should be add doc comments to private members?

 
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
 
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.
 
author and jackaroo
Posts: 12199
280
Mac IntelliJ IDE Firefox Browser Oracle C++ Java
  • 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
 
town drunk
( and author)
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
 
Can you shoot lasers out of your eyes? Don't look at this tiny ad:
create, convert, edit or print DOC and DOCX in Java
https://products.aspose.com/words/java
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!