Summary

Types in packages that are not unconditionally exported by their module are inaccessible by outside users of the API and should be treated as hidden by JavaDoc.

Problem

Implementing shared functionality in a base class that is not itself part of a public API is a useful design pattern. When implemented as non-public class, JavaDoc elides these classes in the type hierarchy and shows their members as belonging to a documented public type. However, it does not apply the same treatment for public types in packages that are not exported unconditionally and therefore not part of the public API of their module, requiring API authors to use the JavaDoc @hidden tag to hide the base class.

Solution

Types in packages that are not exported unconditionally by their modules (in other words, have no or only qualified exports directives) should be treated as if they had a javadoc @hidden tag in the doc comment of their type declaration. This means the type itself is elided from API docs, while its members when inherited by a documented type are shown as belonging to that type.

Specification

Change the behavior of javadoc to treat a type as hidden in API documentation if both of the following conditions apply:

• it is not included in the documented API
• it is in a package that is not exported or only exported to qualified modules by its containing module

Treating a type as hidden has the same effect as if the type declaration contains a javadoc @hidden tag: The type is not shown in the API docs, but its members may be shown as belonging to a documented inheriting type.

Note that since an unnamed module exports all of its packages the second condition above never applies to unnamed modules.

This proposed change has no effect on JDK documentation generated by javadoc, and it allows to remove the existing @hidden tags in JDK source code without changing the generated documentation.