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

Create a mechanism for Implicitly Declared Class javadoc

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P4
    • 22
    • tools
    • None
    • behavioral
    • minimal
    • Hide
      JEP 463, which this CSR supports, is a successive iteration of a preview-feature JEP 445. While it's unlikely that the target audience of either JEP needs javadoc support, this CSR proposes to support implicitly-declared classes as first-class citizens.
      Show
      JEP 463, which this CSR supports, is a successive iteration of a preview-feature JEP 445. While it's unlikely that the target audience of either JEP needs javadoc support, this CSR proposes to support implicitly-declared classes as first-class citizens.
    • File or wire format

    Description

      Summary

      Support implicitly declared (previously known as unnamed) classes in JavaDoc.

      Problem

      JavaDoc somewhat supports implicitly declared classes today. Given enough command-line options, JavaDoc will build documentation for such classes:

      % javadoc --enable-preview --source=21 -package ...

      Here, -package is required to document implicitly declared classes, their constructors, and their methods that are declared with package access:

          -package
                        Show package/protected/public types and members. For 
                        named modules, show all packages and all module details.

      If javadoc is already run with -package or -private, then is all good. However, if it is run with -public or -protected (which is default), then changing it to -package just to document implicitly declared classes might result in also documenting elements that are unrelated to those implicitly declared classes and that should not be documented.

      Solution

      Make JavaDoc document implicitly declared classes regardless of the access level that JavaDoc is run with:

      • document the classes themselves,
      • document those classes' members that are public, protected or declared with package access,
      • if -private is specified, in addition to public, protected or declared with package access members, document private members.

      In addition to that:

      • suppress DocLint and JavaDoc warnings about uncommented class and default constructor declarations, both of which cannot have user-provided comments in implicitly declared classes,
      • do not include default constructor of an implicitly declared class in documentation.

      Specification

      diff --git a/src/jdk.javadoc/share/man/javadoc.1 b/src/jdk.javadoc/share/man/javadoc.1
      index 406c09b9efd..7cb1f4483f1 100644
      --- a/src/jdk.javadoc/share/man/javadoc.1
      +++ b/src/jdk.javadoc/share/man/javadoc.1
      @@ -84,9 +84,9 @@ options, package names, and source file names in any order.
       The \f[V]javadoc\f[R] tool parses the declarations and documentation
       comments in a set of Java source files and produces corresponding HTML
       pages that describe (by default) the public and protected classes,
      -nested and unnamed classes (but not anonymous inner classes),
      -interfaces, constructors, methods, and fields.
      -You can use the\f[V]javadoc\f[R] tool to generate the API documentation
      +nested and implicitly declared classes (but not anonymous inner
      +classes), interfaces, constructors, methods, and fields.
      +You can use the \f[V]javadoc\f[R] tool to generate the API documentation
       or the implementation documentation for a set of source files.
       .PP
       You can run the \f[V]javadoc\f[R] tool on entire packages, individual
      @@ -421,6 +421,15 @@ Prints version information.
       .TP
       \f[V]-Werror\f[R]
       Reports an error if any warnings occur.
      +.PP
      +Note that if a Java source file contains an implicitly declared class,
      +then that class and its public, protected, and package members will be
      +documented regardless of the options such as \f[V]--show-types\f[R],
      +\f[V]--show-members\f[R], \f[V]-private\f[R], \f[V]-protected\f[R],
      +\f[V]-package\f[R], and \f[V]-public\f[R].
      +If \f[V]--show-members\f[R] is specified with value \f[V]private\f[R] or
      +\f[V]-private\f[R] is used then all private members of an implicit class
      +will be documented too.
       .SS Extra \f[V]javadoc\f[R] Options
       .PP
       \f[I]Note:\f[R] The additional options for \f[V]javadoc\f[R] are subject

      Attachments

        Issue Links

          Activity

            People

              prappo Pavel Rappo
              jlaskey Jim Laskey (Inactive)
              Jim Laskey (Inactive), Jonathan Gibbons
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: