Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8173303

Add module-subgraph images to main platform documentation

    Details

    • Subcomponent:
    • Resolved In Build:
      b164

      Backports

        Description

        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

          Attachments

            Issue Links

              Activity

                People

                • Assignee:
                  mchung Mandy Chung
                  Reporter:
                  jjg Jonathan Gibbons
                • Votes:
                  0 Vote for this issue
                  Watchers:
                  7 Start watching this issue

                  Dates

                  • Due:
                    Created:
                    Updated:
                    Resolved: