RFR: JDK-8298405: Support Markdown in Documentation Comments [v31]

[Jonathan Gibbons]

On Thu, 15 Feb 2024 19:15:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java line 571:
>> 
>>> 569:         // of a doclet to be specified instead of the name of the
>>> 570:         // doclet class and optional doclet path.
>>> 571:         // See https://bugs.openjdk.org/browse/JDK-8263219
>> 
>> It's hard to understand this:
>> 
>>> to permit an instance of an appropriately configured instance of a doclet
>> 
>> Also: how is that piece of code used? When I commented it out, no test/langtools:langtools_javadoc tests failed.
>
> 1.  Since forever, and still true, the way to specify a doclet is by its name, and the tool will create the instance for you.  This goes back to the original old days before any API, when the only entry point was the command line.
> This implies that (a) the doclet has a no-args constructor and (b) that all doclet config is done through command line options.  A better solution would be to add new functionality to the various javadoc tool API (some or all of `Main`/`Start`/`DocumentationTool`) so that a client can initialize an instance of a doclet and pass that instance into the API.
> 
> 2. If I understand the question correctly, the code is invoked by using the command-line option `-XDaccessInternalAPI` which is a preexisting hidden feature already supported by `javac`.  It is used in `TestTransformer.java` on line 161.
> 
>         javadoc("-d", base.resolve("api").toString(),
>                 "-Xdoclint:none",
>                 "-XDaccessInternalAPI", // required to access JavacTrees
>                 "-doclet", "TestTransformer$MyDoclet",
>                 "-docletpath", System.getProperty("test.classes"),
>                 "-sourcepath", src.toString(),
>                 "p");

I confirm that `TestTransformer.java` fails as expected with an `IllegalAccessError` if the option is not used.

java.lang.IllegalAccessError: class TestTransformer$MyDoclet (in unnamed module @0x355de863) cannot access class com.sun.tools.javac.api.JavacTrees (in module jdk.compiler) because module jdk.compiler does not export com.sun.tools.javac.api to unnamed module @0x355de863
        at TestTransformer$MyDoclet.run(TestTransformer.java:139)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:589)

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491538120