RFR: 8308715: Create a mechanism for Implicitly Declared Class javadoc

[Pavel Rappo]

Please review this PR to support _JEP 463 Implicitly Declared Classes and Instance Main Method (Second Preview)_ in JavaDoc.

[JEP 463](https://openjdk.org/jeps/463) is the next iteration of [JEP 445](https://openjdk.org/jeps/445), which introduced the ability to have a source file as a launchable, "classless" method bag


% cat HelloWorld.java
/** Run me. */
void main() {
    print("Hello, world!");
}

/** Shortcut for printing strings. */
void print(String arg) {
    System.out.println(arg);
}


which the compiler interprets as a familiar class


final class HelloWorld {

    HelloWorld() {
    }

    /** Run me. */
    void main() {
        print("Hello, world!");
    }

    /** Shortcut for printing strings. */
    void print(String arg) {
        System.out.println(arg);
    }    
}


### How JEP 445 works with JavaDoc today

In JDK 21, javadoc can document such a file **without any changes to the javadoc tool**. The only thing that the user needs to do is to make sure that the following options are present:

* `--enable-preview` and `--source=21`
* `-package`

The first pair of options tells javadoc to use preview features, which JEP 445 is one of. Without these preview-related options, javadoc will raise the following error:


% javadoc --version
javadoc 21

% javadoc HelloWorld.java -d /tmp/throwaway
Loading source file HelloWorld.java...
HelloWorld.java:2: error: unnamed classes are a preview feature and are disabled by default.
void main() {
^
  (use --enable-preview to enable unnamed classes)
1 error


The second option, `-package`, tells javadoc to document classes that are public, protected, or declared with package access (colloquially known as "package private"). Without this option, javadoc will only document public and protected classes, which do not include the interpreted class:


% javadoc --enable-preview --source=21 HelloWorld.java -d /tmp/throwaway
Loading source file HelloWorld.java...
Constructing Javadoc information...
error: No public or protected classes found to document.
1 error


When those additional options are present, javadoc does its job:


% javadoc --enable-preview --source=21 -package HelloWorld.java -d /tmp/throwaway
Loading source file HelloWorld.java...
Constructing Javadoc information...
Creating destination directory: "/tmp/throwaway/"
Building index for all the packages and classes...
Standard Doclet version 21+35-LTS-2513
Building tree for all the packages and classes...
Generating /tmp/throwaway/HelloWorld.html...
HelloWorld.java:7: warning: no @param for arg
void print(String arg) {
     ^
HelloWorld.java:2: warning: no comment
void main() {
     ^
HelloWorld.java:2: warning: use of default constructor, which does not provide a comment
void main() {
     ^
Generating /tmp/throwaway/package-summary.html...
Generating /tmp/throwaway/package-tree.html...
Generating /tmp/throwaway/overview-tree.html...
Building index for all classes...
Generating /tmp/throwaway/allclasses-index.html...
Generating /tmp/throwaway/allpackages-index.html...
Generating /tmp/throwaway/index-all.html...
Generating /tmp/throwaway/search.html...
Generating /tmp/throwaway/index.html...
Generating /tmp/throwaway/help-doc.html...
3 warnings


However, the result does not feel quite right. Firstly, `-package` is too coarse. It includes all top-level classes and their elements, not just the implicit class from `HelloWorld.java`, its default constructor and methods, which are all declared with package access. Secondly, `HelloWorld.java` isn't a first-class citizen in javadoc. That latter fact can be seen from examining stdout and the output directory:

1. DocLint (compiler and javadoc) as well as javadoc itself issue unjust warnings: neither the implicit class nor its default constructor can be documented. The author either does not know about classes and constructors yet (on-ramp audience) or does not care about them (scripts/utilities audience).

   Additionally, because the class' AST node is at the same position as that of the first method declaration, the warning about the undocumented class can be confused with a warning on the first method being undocumented.

2. While such a file is documented as if it were an explicitly declared (normal) class, we might want to dispense with the documentation for the default constructor as it lacks a comment and is an artefact.

### What this PR proposes for JEP 463

1. Leave `--enable-preview` and `--source` as correct and unavoidable until the feature is standardised.
2. "Drill a hole" in javadoc access control to **automatically** allow implicit classes and their public, protected or declared with package access members in documentation.
3. Do not emit warnings for an implicit class and its deault constructor.
4. Do not document an implicit class' default constructor.

-------------

Depends on: https://git.openjdk.org/jdk/pull/16461

Commit messages:
 - Initial commit
 - 8320358: GHA: ignore jdk* branches
 - 8319437: NMT should show library names in call stacks

Changes: https://git.openjdk.org/jdk/pull/16853/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16853&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8308715
  Stats: 256 lines in 6 files changed: 246 ins; 0 del; 10 mod
  Patch: https://git.openjdk.org/jdk/pull/16853.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16853/head:pull/16853

PR: https://git.openjdk.org/jdk/pull/16853