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

Add module-subgraph images to main platform documentation

    XMLWordPrintable

Details

    • 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

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

                Dates

                  Created:
                  Updated:
                  Resolved: