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

NX: JavaDoc

 
Flavio Nobili
Ranch Hand
Posts: 58
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi to all,
Concerning the documentation generated by javadoc, which parameter should I use: -public, -protected, -private or -package?

Regards,
Fl�vio.
 
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 Fl�vio,
If your instructions do not specify anything different, just generate the default documentation.
Personally I wrote javadoc comments right down to the private level, but only generated javadoc at the public level. My theory was that if anyone really wanted to they could generate the other documentation themselves - I had already written all the documentation.
Regards, Andrew
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Fl�vio,
Originally posted by Fl�vio Fran�a:
Concerning the documentation generated by javadoc, which parameter should I use: -public, -protected, -private or -package?

First I generated javadoc with the default parameter (which I believe is -protected) and was surprised to see that 70% of the javadoc documentation I expected to see was missing. I documented everything that could be documented with a javadoc comment! Then I remembered that I'm exceedingly conservative when it comes to access and had made very few classes and methods public, only those that needed to be accessed from other packages. Most of my stuff was private or package private, nothing was protected, and very little was public. I realized that if didn't use javadoc -package a lot of my javadoc documentation would be missing (especially stuff that other people would possibly have made public), so I documented my decision in choices.txt and generated the documentation using javadoc -package. I was happy with the result, and more importantly my examiner didn't seem to mind.
You probably won't get into trouble using the default. My main reason for not using the default was that I'd done a lot of work on the package private javadoc comments and I didn't like not seeing it in the generated javadoc. If you haven't been so conservative with your access then the default will probably suit you just fine.
[ March 03, 2004: Message edited by: George Marinkovich ]
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic