-
Enhancement
-
Resolution: Fixed
-
P3
-
9
-
b164
Issue | Fix Version | Assignee | Priority | Status | Resolution | Resolved In Build |
---|---|---|---|---|---|---|
JDK-8178186 | 10 | Mandy Chung | P3 | Resolved | Fixed | b04 |
We should add images of the module subgraph to each module's documentation (module summary in the API docs.)
The very, very simplest way to do this is to manually edit a <img> tag into each module's module-info.java doc comment, but that will *require* the image to be generated and made available in all environments building the docs.
A relatively easy but more flexible approach would be to create and use a new "taglet" to implement a new custom tag @moduleGraph (as a block tag) or {@moduleGraph} (as in inline tag.) Providing such a tag(let) should be relatively easy. Depending on the build environment, javadoc could be configured to either ignore the tag (if the graphs are not available) or to create an <img> tag if the graph is available.
This would entail 4 subtasks:
1. Create and provide a suitable taglet, perhaps as a "build tool"
2. Update the module-info files to use the new tag.
3a. Update the Makefiles to make the graphs available in the right place, using the "dot" tool to convert .dot files into .png files.
3b. Update the Makefiles to have javadoc use the new taglet.
Where should the image files be placed? JDK-8164822 is an RFE to organize the output by module, but that will not be done soon. Currently, module-specific files are all named <module-name>-<suffix>.<extn> E.g.
build/linux-x86_64-normal-server-release/images/docs/api/java.base-frame.html
build/linux-x86_64-normal-server-release/images/docs/api/java.base-summary.html
build/linux-x86_64-normal-server-release/images/docs/api/java.base-type-frame.html
That implies the graph file should be similarly named, such as
build/linux-x86_64-normal-server-release/images/docs/api/java.base-graph.png
The very, very simplest way to do this is to manually edit a <img> tag into each module's module-info.java doc comment, but that will *require* the image to be generated and made available in all environments building the docs.
A relatively easy but more flexible approach would be to create and use a new "taglet" to implement a new custom tag @moduleGraph (as a block tag) or {@moduleGraph} (as in inline tag.) Providing such a tag(let) should be relatively easy. Depending on the build environment, javadoc could be configured to either ignore the tag (if the graphs are not available) or to create an <img> tag if the graph is available.
This would entail 4 subtasks:
1. Create and provide a suitable taglet, perhaps as a "build tool"
2. Update the module-info files to use the new tag.
3a. Update the Makefiles to make the graphs available in the right place, using the "dot" tool to convert .dot files into .png files.
3b. Update the Makefiles to have javadoc use the new taglet.
Where should the image files be placed? JDK-8164822 is an RFE to organize the output by module, but that will not be done soon. Currently, module-specific files are all named <module-name>-<suffix>.<extn> E.g.
build/linux-x86_64-normal-server-release/images/docs/api/java.base-frame.html
build/linux-x86_64-normal-server-release/images/docs/api/java.base-summary.html
build/linux-x86_64-normal-server-release/images/docs/api/java.base-type-frame.html
That implies the graph file should be similarly named, such as
build/linux-x86_64-normal-server-release/images/docs/api/java.base-graph.png
- backported by
-
JDK-8178186 Add module-subgraph images to main platform documentation
- Resolved
- blocks
-
JDK-8176785 Add build support to generate PNG file from .dot file
- Resolved
- duplicates
-
JDK-8164393 Provide a javadoc descriptions for jdk.httpserver module
- Closed
-
JDK-8175848 Provide a javadoc description for jdk.jsobject module
- Closed
- relates to
-
JDK-8176836 Provide Taglet with context
- Closed
-
JDK-8176785 Add build support to generate PNG file from .dot file
- Resolved
(1 relates to)