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

[Jonathan Gibbons]

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

>> 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)

Generally, the error occurs because the `MyDoclet` class is run in a different class loader than that used for the test.  The class loader for the test already has the necessary access permissions given, from the lines in `@modules` in the `jtreg` test description.  Ideally, we could call `new MyDoclet()` in the main test code, and pas the instance in to the `javadoc` call and from there to the javadoc `Start` method.

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

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