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

Got Them JavaDoc Blues

 
Matt DeLacey
Ranch Hand
Posts: 318
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hey All,
I've started doing all the JavaDoc stuff. I don't mind most
of it but I have an interface called DataClient. It is implemented by RemoteDataClient and LocalDataClient. All 3 of these have all the same methods. Do I have to put javadoc comments around all the methods of all 3 classes? Slowly...falling...asleep. Gosh, I appreciated the value of
good documentation, but it can be frustrating.
With Respect,
Matt DeLacey
 
Abhijeet Premkumar
Greenhorn
Posts: 18
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Matt,
You don't need to javadoc the implementing classes too. A "Specified by" link appears in the appropriate places when you run the javadoc tool.

---
Abhijeet
Originally posted by Matt DeLacey:
Hey All,
I've started doing all the JavaDoc stuff. I don't mind most
of it but I have an interface called DataClient. It is implemented by RemoteDataClient and LocalDataClient. All 3 of these have all the same methods. Do I have to put javadoc comments around all the methods of all 3 classes? Slowly...falling...asleep. Gosh, I appreciated the value of
good documentation, but it can be frustrating.
With Respect,
Matt DeLacey

 
Jane Griscti
Ranch Hand
Posts: 3141
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Matt,
Found this in the JavaDoc documentation at http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Automatic re-use of method comments
You can avoid re-typing doc comments by being aware of how Javadoc duplicates (inherits) comments for methods that override or implement other methods. This occurs in three cases:
  • When a method in a class overrides a method in a superclass
  • When a method in an interface overrides a method in a superinterface
  • When a method in a class implements a method in an interface
    In the first two cases, if a method m() overrides another method, Javadoc will generate a subheading "Overrides" in the documentation for m(), with a link to the method it is overriding.
    In the third case, if a method m() in a given class implements a method in an interface, Javadoc will generate a subheading "Specified by" in the documentation for m(), with a link to the method it is implementing.
    In all three of these cases, if the method m() contains no doc comments or tags, Javadoc will also copy the text of the method it is overriding or implementing to the generated documentation for m(). So if the documentation of the overridden or implemented method is sufficient, you do not need to add documentation for m().
    If you add any documentation comment or tag to m(), the "Overrides" or "Specified by" subheading and link will still appear, but no text will be copied.

  • Looks like you don't have write all the comments
    Hope that helps.
    ------------------
    Jane Griscti
    Sun Certified Programmer for the Java� 2 Platform
    [This message has been edited by Jane Griscti (edited April 07, 2001).]
     
    • Post Reply
    • Bookmark Topic Watch Topic
    • New Topic