How to document Interfaces and Implementations?
Something that I have been thinking about over the last two day is what is the correct method for documenting, as in Javadocs, Interfaces and their implementations? Generally, what I have been doing is putting the bulk of the Javadoc comments in the Interface and then either copy/pasting the comments into the implementation or creating a smaller comment. However, I can’t see how either of these methods is correct.
I know Eclipse uses a special little annotation-like thingy to tell you to go look at the docs for the Interface, but I am not sure if this is standard as it clearly states that it is not a Javadoc.
I guess the idea is that the Interface holds a general comment about what the method should do while the implementation should contain details of what the implemented method actually does. On the surface, this seems obvious. But what happens when you only have one implementing class? Should you still try and come up with a general comment for the Interface and a specific one for the implementing class?
Anyone have any ideas on the best way of commenting Interfaces versus Implementations?
