• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

javadoc for implementing public methods

 
Dieskun Koper
Ranch Hand
Posts: 85
  • Mark post as helpful
  • send pies
  • 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
 
Mark Spritzler
ranger
Sheriff
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • 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
  • 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.
 
Raj Nagappan
Ranch Hand
Posts: 38
  • Mark post as helpful
  • send pies
  • 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
  • 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.
 
It is sorta covered in the JavaRanch Style Guide.
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic