How to override the javadoc for a final method in a sub class?

Question

public class BaseClass {
    /**
     * Gets the value.
     */
    public final String getValue() {
        // returns something.
    }
}

public class SubClass extends BaseClass {
    /**
     * Gets the value.
     * <p/>
     * The value is meaningless for SubClass.
     */
    @Override // Cannot override final method
    public final String getValue() {
        super.getValue(); // Not overriding implementation, just javadoc
    }
}

I do not need to change the implementation of the final method, I just want to change the Javadoc for it.

Answer 1

Simply spoken: you can't do that. If at all, you could put some javadoc at the definition of that child class explaining that the behavior of that one final method has been changed. And if you can do that - you could change the javadoc on the base class to say: "sub classes might invalidate this method" or something alike.

Beyond that, you should understand that this is also a questionable idea conception wise.

Inheritance is not primarily about code reuse. It is about expressing that some class A is-a B, because A extends B. So when you decide to make a method meaningless on a subclass, you are basically invalidating the contract of the super class. And that is simply not good practice (see the Liskov substitution principle for why you have to be careful when modifying the contract of inherited methods).

You see, that keyword final is not only information to the compiler. It also expresses intent by the person who used it for that very method. This person said: "I don't want that subclasses temper with this method!"

Answer 2

This is not foreseen by Java, hence it is not possible to do using standard Java tools. You mya provide a more detailed explanation on the class level though.

You can also try to look at Javadoc API (Doclet API) and search for some custom implementations of it or implement your own extension, e.g. introduce new annotation on the class level, and implement custom Javadoc generator to respect those. I'm not aware if something like this already exists though.

Update: Also see the GhostCat answer, he has a bunch of reasons why you should not do that.