Interfaces For Javadoc

As an educated guess I would suspect it is something like this:

 public interface MyClassPublicAPI {
   /**
    * I do all kinds of amazing things!
    */
   public void myMethod() {}
 }

 public MyClass implements MyClassPublicAPI {
   ... code that must be maintained

   public void myMethod() {
     ... code that must be maintained
   }

   ... code that must be maintained
 }

Interface method descriptions are automatically used by the JavaDoc tool so all the documentation of DocumentMyClass will be copied into the documentation for MyClass unless it defines Javadoc comments for implemented interfaces.

Anyone else familiar with this idiom?

-- JamesHollidge

The advantage of this is that JavaDoc is kept out of functional code, so code that developers must be able to read and understand frequently is kept uncluttered but documentation can still be generated for the class by the javadoc tool.