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: Sun "Must" and JavaDoc

 
Javini Javono
Ranch Hand
Posts: 286
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,
""
""
**************************************
My question deals with the javadoc option which can be
one of the following:
-public
-protected
-package
-private
The one must directive above: "."
is all inclusive and I will follow this in my submission.
In other words, since I keep every class and field "as private
as possible" either by making the class private or package
friendly (unless it is used by classes outside of the package
or it is used in inheritance),
then it would seem that for my submission that I would
need to use the
-private
option to ensure that every class and interace I submit is documented
with JavaDoc.
Certainly one can't go wrong using the
-private
option. My only concern would be that the examiner may be wading
through more JavaDoc html files than I would ever want to look at
(for instance, during development, for my own purposes, I'm more
inclined to create JavaDoc with the -public or -protected options
since my reasoning occurs at this mid-level area when I'm coordinating
the complete project).
So, I'll be submitting my JavaDoc with the
-private
option (which documents everything), and creating JavaDoc comments
for every class and interface and for every method and its arguments
(whether that class, interface, or method is public, protected,
package friendly, or private).
I will _not_ be creating JavaDoc comments for local variables within
a method; though, as I read more about JavaDoc, perhaps I will; but,
I'm inclined to think that local method variables don't need JavaDoc
comments, and, depending on the method, may need no comments at all.
Any opinions or comments?
Thanks,
Javini Javono
[ January 07, 2004: Message edited by: Javini Javono ]
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I did the same thing, the only public things in my implementation are those things that are needed in another package. So if you produce javadoc (default public) your documentation set is pretty limited, too limited in my opinion. On the other hand, since I commented all sorts of private member variables and methods and I seem to have a lot of them I wouldn't want a reviewer to have to look at so much detail (although it may be appropriate for a programmer's guide and I mention this in the design choices document). So I can't support javadoc -private, I think it ends up producing so much documentation of so many details that it obscures the big picture. As a compromise I submitted javadoc -package.
I don't use javadoc style comments for variables in methods since I don't believe its possible to do so. I mean you can use javadoc formatted comments if you want to but javadoc won't pick them up. You said:
I'm inclined to think that local method variables don't need JavaDoc
comments, and, depending on the method, may need no comments at all.

I agree.
Hope that helps,
George
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic