wood burning stoves 2.0*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Providing Javadoc for private methods Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Providing Javadoc for private methods" Watch "Providing Javadoc for private methods" New topic
Author

Providing Javadoc for private methods

Khaled Mahmoud
Ranch Hand

Joined: Jul 15, 2006
Posts: 361
Hello,
I am doing the "Bodggit and Scraper" assignmet and i finished the Data Access part and i am now documenting the code. Should i provide javadoc
for private methods.

I am also providing javadoc comments for all the classes,wheather they were
public or default access.I am not sure if this correct or not.
[ October 06, 2006: Message edited by: Khaled Mahmoud ]

SCJP, SCJD,SCWCD,SCDJWS,SCEA 5 MCP-C#, MCP-ASP.NET - http://www.khaledinho.com/
Life is the biggest school
Jeroen T Wenting
Ranch Hand

Joined: Apr 21, 2006
Posts: 1847
Your Javadoc is your main form of documentation for your maintenance programmer.
I provide it for everything except private datamembers (and even for some of them if their function isn't immediately apparent).


42
Anthony Bull
Greenhorn

Joined: Nov 08, 2004
Posts: 8
The assignment text clearly states the public interface should be completely javadoc'ed.

In the real world you wouldn't javadoc your private interface as it provides no value to someone using the code, so why do it here? Simple java comments are fine above a private method.
Jeroen T Wenting
Ranch Hand

Joined: Apr 21, 2006
Posts: 1847
in the real world you often provide no documentation at all
That doesn't mean you shouldn't though, theory and practice clash there and badly.
Mike Tilling
Ranch Hand

Joined: Feb 17, 2006
Posts: 86
Hi

When I run javadoc the resultant documentation contains comments of the classes members but it does not include the classes comments. For example

/**
* class comment
*/
public class ClassExample {

/**
* method comment
*/
public methodExample {
int a = 1+2;
}
}


When I run javadoc tool I obtain an html file that contains the methodExample comment but it does not contain the ClassExample comment.

How can I use javadoc so that the resultant html files include the class comments.
Robert Bar
Ranch Hand

Joined: Jun 29, 2006
Posts: 38
Hi,

Generally I agree with Anthony. In most of situations providing javadoc for private members it's a waste of effort.

Mike, see following documents:

- how to write doc comments.

- requirements for writing API specifications

regards,
Robert
[ October 08, 2006: Message edited by: Robert Bar ]
Khaled Mahmoud
Ranch Hand

Joined: Jul 15, 2006
Posts: 361
Hello call
I can see a use for providing javadoc for private methods.The IDE
tools you are providing will display the information about the method
when you call that method from a method inside the class.
But i meant by my question is:

Will i lose points by providing javadoc for private methods.
I provided javadoc for all methods.
I had about 18 (classes and interfaces) in the data access module inculding the exceptions.Writing javadoc for all of them was so tedious task.
Jeroen T Wenting
Ranch Hand

Joined: Apr 21, 2006
Posts: 1847
you only loose points if you either don't provide enough or if what you provide is incorrect.
 
Consider Paul's rocket mass heater.
 
subject: Providing Javadoc for private methods
 
Similar Threads
javadoc quesion - private methods/classes ?
javadoc
Doubt from Joshua Bloch's item 14
Documentation Comments (scjd)
JavaDoc private fields and methods