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

Listing (sub)packages at package level of API documentation

    XMLWordPrintable

    Details

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

      Description

      When browsing JavaSE API specification for a package that contains complex and large domain area ('java.nio', 'java.security' etc.) sub-packages that a higher level package encloses are often mentioned in the text of the package specification - for example 'java.nio.charset', 'java.nio.channels' are met in the description of 'java.nio' package. However sometimes subpackages are not explicitly mentioned (like for 'java.security') and yet they are not “automatically” being listed in the JavaSE API javadoc along with other entities that particular package encloses (interfaces, classes, enums, exceptions, errors etc.)
      So to find out that for example there are
       - java.security.cert
       - java.security.interfaces
       - java.security.spec
      enclosed in 'java.security' package user needs to navigate back to the module level spec
      https://docs.oracle.com/en/java/javase/15/docs/api/java.base/module-summary.html
      or go to “All packages” list
      https://docs.oracle.com/en/java/javase/15/docs/api/allpackages-index.html

      It is rather surprising that sub packages are not listed in JavaSE API javadoc along with other items that specific package includes.
      It seems expected and very convenient that say https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/security/package-summary.html would contain its (sub)package summary with short descriptions, similar to https://docs.oracle.com/en/java/javase/15/docs/api/allpackages-index.html

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              hannesw Hannes Wallnoefer
              Reporter:
              dbessono Dmitry Bessonov
              Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: