This week's giveaway is in the Android forum.
We're giving away four copies of Android Security Essentials Live Lessons and have Godfrey Nolan on-line!
See this thread for details.
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Javadoc for all or public classes? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Android Security Essentials Live Lessons this week in the Android forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Javadoc for all or public classes?" Watch "Javadoc for all or public classes?" New topic
Author

Javadoc for all or public classes?

Brian Kelly
Ranch Hand

Joined: Jan 04, 2007
Posts: 54
"...and javadoc style comments must be used for each element of the public interface of each class."

"Provide javadoc documentation for all classes you write."

And under deliverables:
"A subdirectory called javadoc, containing HTML/Javadoc documentation for all classes and interfaces you are submitting. "

So which is it???

Javadoc for all or public?

I was going to do it for everything (private classes and methods) but it's driving me insane, so I want to check if it's necessary to write javadocs for everything??


SCJA, SCJP (1.4), SCJD
Mark Smyth
Ranch Hand

Joined: Feb 04, 2004
Posts: 288
Originally posted by Brian Kelly:
"...and javadoc style comments must be used for each element of the public interface of each class."

"Provide javadoc documentation for all classes you write."

And under deliverables:
"A subdirectory called javadoc, containing HTML/Javadoc documentation for all classes and interfaces you are submitting. "

So which is it???

Javadoc for all or public?

I was going to do it for everything (private classes and methods) but it's driving me insane, so I want to check if it's necessary to write javadocs for everything??


Javadoc all classes default, protected and public (class descriptions) and at least all public methods of each class. I provided javadoc for the protected members and methods as well. I dont think there is any need to javadoc private menbers and methods, as users of you class should not know this information anyway. Maybe regular comments for these would be fine.

Regards,
Mark.


SCJP<br />SCJD
Brian Kelly
Ranch Hand

Joined: Jan 04, 2007
Posts: 54
Thanks. Sounds sensible!
Zhixiong Pan
Ranch Hand

Joined: Jan 25, 2006
Posts: 239
Do I need to add comments in front of the class definition to explain why that class is created?


SCJP 1.4 SCJD
Zhixiong Pan
Ranch Hand

Joined: Jan 25, 2006
Posts: 239
BTW, most of my class variables are private. Should I leave them uncommented?
Mark Smyth
Ranch Hand

Joined: Feb 04, 2004
Posts: 288
Originally posted by Zhixiong Pan:
BTW, most of my class variables are private. Should I leave them uncommented?


Zhixiong you should have javadoc comments explaining what the purpose of each class is. For private variables you shouls still comment them with at least a one line regular comment explaining what each is for.

Mark
Zhixiong Pan
Ranch Hand

Joined: Jan 25, 2006
Posts: 239
Mark, I agree with you. And how about comments for a class to explain the motivation of creating that class.
Tim Anlauf
Greenhorn

Joined: Oct 11, 2006
Posts: 22
What about implemenation of interfaces, do I have to add a comment to the public methods ?

For Example the the DBAccess interface defines the comments, do I have to add to an extra comment in Data class ?

Tim
Zhixiong Pan
Ranch Hand

Joined: Jan 25, 2006
Posts: 239
I don't think so. The comments given by Sun can be enough.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Javadoc for all or public classes?
 
Similar Threads
B&S: javadoc
NX: Should I reformat the provided interfaces comments?
java doc for private members
Disallowed to use private inner classes?
Javadoc documentation??