Search code examples
javadoc

Javadoc: Difference between "Methods inherited from" and "Methods declared in"

The JDK Java docs for Java < 10 have a section called "Methods inherited from" which lists methods which are declared in the parent class / interface. However starting with Java 10 this section is called "Methods declared in".

For comparison:

Is there a difference between them or is this only a change of the section name?

Solution

  • In Java 10 the option --override-methods (detail|summary), was added to the javadoc command:

    The intention was to reduce the noise when methods are implemented or overridden, but the documentation remained unchanged.

    Modes

    detail mode (default)

    The detail mode is the default when you use javadoc without specifying override-methods.

    It behaves the way the documentation has been generated before:

    • If a method is not overridden, it will be in the "Methods inherited from" section.
    • If a method is overridden, it will be documented under "Method Detail", regardless of whether its signature or documentation was changed as well.

    summary mode

    • If a method is overridden and its documentation is changed, it will be documented under "Method Detail".
    • Otherwise it will be listed under "Methods declared in".

    The summary mode is now used to generate the JDK documentation (JDK-8189706).

    Be aware that this mode is currently bugged because it ignores some changes to the method signature which should be documented, see JDK-8223607.

    Conclusion

    You will either see a "Methods inherited from" or a "Methods declared in" section.
    When comparing two documentations (one with "inherited from", the other with "declared in") for the same class, then the one with "inherited from" might list more methods under "Method Detail", while for the "declared in" one, some methods are instead in the "declared in" section.

    So yes, there is a difference between them.

    Example

    The difference in behavior can be seen for example for the java.time.temporal.ChronoUnit class:

    • Java 8: Listed under "Method Detail"
    • Java 12: Contained in "Methods declared in class java.lang.Enum"; see also the source to verify that the method is actually overridden