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

javadoc HELP page

    XMLWordPrintable

    Details

    • Type: Enhancement
    • Status: Resolved
    • Priority: P3
    • Resolution: Fixed
    • Affects Version/s: 17
    • Fix Version/s: 17
    • Component/s: tools

      Description

      Here are some issues arising from reading the HELP page generated in each run of javadoc.

      1. I find the top level heading confusing. It seems to be using the singular "This API Document" to refer to the overall collection of pages.

      2. The first sentence is misleading/wrong. It suggests a correlation between pages and items in the navigation bar. That correlation has worn out over time. Maybe it would be better to describe the contents of the HELP page as a list of the various different kinds of pages, some of which are linked from the navigation bar.

      2a. Maybe replace the initial heading and first sentence (paragraph) with a new section about "Navigation".

      3. The <h2> headings corresponding to navigation bar items, except when they don't. Arguably, "Annotation Interface" and "Enum Class" should be subheadings of Class or Interface". "Record" is missing. Arguably it would be better to merge the lists, maybe indicating which list items are specific to the kind of class or interface

      4. The contents of the "Package" list do not include "Records", and if/when "Records" are added, "six" will become "seven". (We should avoid the number.)

      4a. (Likewise, avoid the "three" under "Module".)

      ** Not a HELP item: maybe package pages should be changed to use tables, with tabs for what are now separate sections.

      5. The Index entry could be more informative.

      6. Serialized Form, Constant Field Values and System Properties are not navigation bar entries. (See #2).

      7. The Serialized Form info is slightly out of date. You can access it from the INDEX page.

      8. Constant Field Values and System Properties: should mention how to find it (e.g. INDEX page.)

      9. Under "Search" the word "the" should not be included in the link to "Javadoc Search Specification", since the word is not in the title. Or, it should be in then title, and capitalized.

      ## Stretch Goal

      The HELP link in the navigation bar for each kind of page should link to the relevant section in the HELP page. This can be done by associating a `HtmlId` (within the HELP page) with each `Navigation.PageMode`. (The minor implementation complexity is that the page is generated by localizable code, meaning that it is not as easy as simply adding is into the content on the HELP page.) Most PageMode values have an obvious heading for the target of a link. The exceptions are `ALL_CLASSES` and `ALL_PACKAGES` which are currently just phrases, and `DOC_FILE` which currently has no obvious target text.

        Attachments

          Activity

            People

            Assignee:
            jjg Jonathan Gibbons
            Reporter:
            jjg Jonathan Gibbons
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved: