What is the correct way to write javadoc in abstract methods

Question

public interface ISomething
    /**
     * This method does something!
     */
    public void something();
}

public abstract class AbstractSomething implements ISomething
{
    /**
     * See {@link #doSomething()}
     */
    public final void something()
    {
        doSomething();
        // Do something else...
        ...
    }

    protected abstract void doSomething();
}

public class ConcreteSomething extends AbstractSomething
{

    /**
     * Concrete implementation of doSomething(). It does... something!
     */
    @Override
    protected void doSomething()
    {
        // Actually do something...
        ...
    }
}

So I have a class hierarchy that looks like this one. The idea is to use the public final something() - then abstract - doSomething() pattern so that extending classes would be obligated to call super(), e.g. Andrzej answer's

Then, I will eventually have several implementations that extend AbstractSomething. The clients of this code will then instantiate these implementations and use the ISomething methods.

Something like this:

public class Main
{
    public static void main(String[] args)
    {
        ConcreteSomething concrete = new ConcreteSomething();
        concrete.something();
    }
}

So the question is, using this design idiom is there a correct way to write a good javadoc for the hierarchy?

By correct I mean: When clients call concrete.something() I'd want them to see the ConcreteSomething#something() javadoc. Since the method is final, however, I can't simply override it and write a concrete javadoc. In addition, my clients won't see the doSomething() method since it's protected so I can't put the concrete javadoc in there too.

So in other words, I probably need the opposite of {@InheritDoc} :)

Any suggestions?

Answer 1

The problem is similar to an interface's documentation. Client's will use the abstraction and will mainly see that abstraction's generic documentation. In your case, the best you can do is add the documentation to the constructor of each concrete class. At least this way the client will see the details of the implementation and you can include relevant @link and @see if needed.