• 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 Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Providing Javadoc for private methods

 
Ranch Hand
Posts: 361
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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 ]
 
Ranch Hand
Posts: 1847
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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).
 
Greenhorn
Posts: 8
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 1847
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Ranch Hand
Posts: 86
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Ranch Hand
Posts: 38
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 361
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 1847
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
you only loose points if you either don't provide enough or if what you provide is incorrect.
reply
    Bookmark Topic Watch Topic
  • New Topic