• 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

javadoc for implementing public methods

 
Ranch Hand
Posts: 85
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hello,

I am wondering how to document methods that implement methods defined (and documented with javadoc) in interfaces.
For example:

public interface DBMain {
/**
* Searches blah blah
* @tag blah
*/
public search();

How should I document my implementing class?

public class Data {
/**
* [ copy and paste from interface ?? ]
*/
public search() {

Copying and pasting sounds like a maintenance horror.
If I do not write any comment for the implementing method, javadoc will copy the documentation from the interface. But my spec says:
"javadoc style comments must be used for each element of the public interface of each class"
I assume "each element of the public interface of each class" means each public method, so I am considering copying and pasting the comments.

I'd like to hear your opinions..

Thanks,
Dies
 
ranger
Posts: 17347
11
Mac IntelliJ IDE Spring
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
You interface should have the Javadoc, the implementing class does not need to javadoc, since it is already in the interface.

Mark
 
Dieskun Koper
Ranch Hand
Posts: 85
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I noticed with javadoc, when you do not write any javadoc for a public method, it sometimes copies it from the interface with a comment as follows:
Description copied from interface: xxx
However, it only seems to do that for the first interface in the implements clause.
For instance, I have a table model extending AbstractTableModel, and it will not generate javadoc for methods like getColumnCount unless I explicitely add 'implements TableModel' to my class definition.
I wonder why that is.
 
Ranch Hand
Posts: 38
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
You can use @inheritDoc to force a method to repeat the javadoc from its interface or superclass. Very effective.

Raj.
 
Dieskun Koper
Ranch Hand
Posts: 85
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Thanks Raj.
I already submitted my assignment, but I'll have a look at it anyway.
I was thinking of reading the javadoc manual, also when I got a warning for all the <br>'s I used, but somehow I forgot.
 
reply
    Bookmark Topic Watch Topic
  • New Topic