Question

What is the best way to properly and usefully document a function of an anonymous object? I am doing some programming with Soar (API here), and have code that looks something like this:

/**
 * 
 * @return handler that does blah
 */
public static RhsFunctionInterface functionBlah() {
    return new Kernel.RhsFunctionInterface() {
        /**
         * Does blah
         */
        @Override
        public String rhsFunctionHandler(int eventID, Object data,
                String agentName, String functionName, String arguments) {
            return null;
        }
    };
}

When it is important to know what the function of the returned object does, what it expects for parameters, etc., I’m not sure what to write down. Eclipse seems to ignore the javadoc’s method, and I really don’t want to write separate classes for each of the handlers just for documentation purposes.

Answer 1

The method should not need any documentation at all, as it’s the implementation of an interface, and that interface should be documented. The implementation of an interface behaves according to that.