On Thu, 30 Nov 2023 16:09:26 GMT, Pavel Rappo <pra...@openjdk.org> wrote:
>> 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... > > Pavel Rappo has updated the pull request incrementally with two additional > commits since the last revision: > > - Remove ugly dependency on Utils > - Improve test TL;DR: approved. "One of these days" we should try and split the `jdk.javadoc` module in two: one for the "tool" part, and another for the "standard doclet" part. In that split world, the "tool" part is deeply intertwined with the `javac` front end, and gets to access `javac` front-end internals almost without restriction. As such, it does not need to use `WorkArounds`. In module terms, it would be given qualified access into `jdk.compiler` internals. And, in that split world", the doclet part would/could/should be a pure client of the Language Model API, to reflect over the declarations, and the Compiler Tree API, to access the documentation comments. And, for that module, `WorkArounds` is used to workaround shortcomings of those public API. So it would reluctantly be given "temporary" access to `javac` internals, until the workarounds can be eliminated. All of which is to say that `ElementsTable` will have an unnecessary forward dependency on `WorkArounds`, which belongs in that hypothetical "other" module. But at least the method the method has a well placed comment. `DocLint` is using access to `javac` internals, but `DocLint` is currently something of an orphan stepchild of `javac` and `javadoc` and deserves more significant remedial attention of its own, so gets a pass for now. ------------- Marked as reviewed by jjg (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/16853#pullrequestreview-1757936283
