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

Listing (sub)packages at package level of API documentation

    XMLWordPrintable

Details

    • Enhancement
    • Resolution: Fixed
    • P3
    • 17
    • None
    • 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

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

              Dates

                Created:
                Updated:
                Resolved: