How does the Javadoc deal with the visibility of modules in Java 9?

Question

The Javadoc tool generates documentation based on the accessibility modifier. By default, it document all public and protected classes, fields and methods. This can be changed with the following options:

-public
Shows only public classes and members.

-protected
Shows only protected and public classes and members. This is the default.

-package
Shows only package, protected, and public classes and members.

-private
Shows all classes and members.

Java 9 introduces the concept of modules, and project Jigsaw applies it to the existing JDK. A talk by Mark Reinhold (3rd in a series of talks about modules) shows how the public modifier now has different levels of accessibility, depending on the visibility of the module (via exports):

• public to everyone
• public but only to specific modules
• public only within a module

Since now not all public members are accessible, it would make less sense to continue with the same Javadoc generation scheme. Only members which are exposed with a "sufficient" level should be documented.

Is the Javadoc module-aware? Are there command options in addition to the ones above to handle the extra exposure layer? For public members which are exposed only to specific modules, does the Javadoc list these, as in

public <module1, module2> static void getDefaultThing()

?

Answer 1

javadoc has new options that allow you to select which items are documented at the module, package, type and member level. Using an EA version of JDK 9, look for new --module, --show-* options, and --expand-requires options.

The existing options -public, -protected, -package, -private options have been redefined in terms of the new --show-* options, although their command line help still needs to be updated.

The handy-dandy conversion table is:

-public
      --show-module-contents api --show-packages exported --show-types public --show-members public

-protected   (the long-standing default)
      --show-module-contents api --show-packages exported --show-types protected --show-members protected

-package
      --show-module-contents all --show-packages all --show-types package --show-members package

-private
      --show-module-contents all --show-packages all --show-types private --show-members private 

In general, continue to use the default to generate documentation for users of an API, and maybe use -package or -private to generate documentation for the developers of an API. For more fine-grain control, use the underlying --show-* options.