JDK-8194553 : Allow doc-files for module-info.java
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P3
  • Status: Open
  • Resolution: Unresolved
  • Submitted: 2018-01-04
  • Updated: 2018-10-23
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
tbdUnresolved
Related Reports
Relates :  
JDK-8195795 - Organize output files by module/package, not just package
Description
We can create a doc-files directory near a Java source file and the javadoc of that class can link to files inside doc-files. However, the doc-files near module-info.java is not copied by javadoc.

I can understand the problem here. All module-name-summary.html files are in the same directory, which means their separate doc-files will be merged into one.

Currently I can put doc-files into a package and put a deep link in module-info.java, but I am not sure if the path of module-name-summary.html would change in the future.
Comments
If we can figure a way to abstract the link, with {@link} instead of <a href=...>, then a change in layout could be transparent.
04-01-2018
Depending on how we design this, if we change the layout, the choice of layout could be a "policy" option, giving users the ability tp select the layout for an interim period. (Not ideal, just possible).
04-01-2018
The output layout of javadoc tool needs to be agreed upon, the predicating factor is the index file format for cross linking documents, and this needs to be designed in such a way to maintain backward compatibility.
04-01-2018