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

Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec)

    XMLWordPrintable

Details

    • b17
    • generic
    • generic

    Description

      The J2SE specification is the document generated by javadoc plus
      all specs that it references (usually by way of hyperlinks).

      This is a request for a specification bibliography, in the sense
      that it would be a summary of all documents outside the doc
      bundle that are part of the spec.

      In 1.4 we published to licensees a page that listed documents
      that comprised the J2SE spec. It would be useful to incorporate
      such a list into the J2SE specification, but only if it could be
      automatically generated from spec references in the Javadoc, as
      it duplicates information already in the spec.

      For example, here is a reference under the heading "Additional Specification"

         AWT Focus Subsystem (which links to a file that resides in the source tree)
         http://java.sun.com/j2se/1.5.0/docs/api/java/awt/package-summary.html#package_description

      As another example, here is a reference under the heading "Package Specification":

         JMX Specification (which links off to jcp.org)
          http://java.sun.com/j2se/1.5.0/docs/api/javax/management/package-summary.html#spec

      We could work out some kind of tagging that identifies the document titles
      and URLs to pick up and place on the summary page.

      The guiding principle would be something like:

         This spec is composed of this document plus all documents referenced
         under specification headings such as "Additional Specifications" or
         "Package Specification". Non-normative documentation includes examples
         and documentation that is identified by <some "non-spec" subhead>.

      ###@###.### 2005-04-07 01:49:15 GMT

      Javadoc block tags could be created that are similar to @see links.

      In discussions with Stan and Patrick (the TCK manager), we lean
      toward having a javadoc tag to indicate an "external" document is
      part of the spec. Perhaps something along the lines of this:

        @refspec <a href="http://www.unicode.org">UNICODE Standard 4.0</a>
        @extspec <a href="http://www.unicode.org">UNICODE Standard 4.0</a>
        @addspec <a href="http://www.unicode.org">UNICODE Standard 4.0</a>
        @seespec <a href="http://www.unicode.org">UNICODE Standard 4.0</a>
        @supplspec <a href="http://www.unicode.org">UNICODE Standard 4.0</a>

      It would be similar a @see tag in that it would generate a section
      on that same page:

        Additional Specification
            * <a href="http://www.unicode.org">UNICODE Standard 4.0</a>

        in this example, on the page java.lang.Character:
        http://rhea:91/j2se/1.5.0/docs/api/java/lang/Character.html

      plus it would add this entry to a new external reference specification
      page that javadoc would generate, such as:
      http://swpubs.sfbay/writing/j2se/1.4.0/OEMspec/api/Additional/index.html

      ###@###.### 2005-05-09 18:59:47 GMT

      Attachments

        Issue Links

          Activity

            People

              jjg Jonathan Gibbons
              dkramersunw Douglas Kramer (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:
                Imported:
                Indexed: