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

Listing (sub)packages at package level of API documentation

XMLWordPrintable

    • Icon: Enhancement Enhancement
    • Resolution: Fixed
    • Icon: P3 P3
    • 17
    • None
    • tools

      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

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

              Created:
              Updated:
              Resolved: