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

[Jonathan Gibbons]

On Tue, 6 Feb 2024 19:27:55 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 1:
>> 
>>> 1: /*
>> 
>> This transformer seems to break positions of the `RawTextTree`.
>> For javadoc like:
>> 
>>                         /// Markdown test
>>                         ///
>>                         /// @author testAuthor
>> 
>> without this transformer, taking the start and end positions of the `RawTextTree` and taking the text between these positions will lead to: `[Markdown test, testAuthor]`. With this transfomer, it leads to `[Markdown test, Markdown t]`, which is clearly suspicious.
>> 
>> Testcase:
>> 
>> /*
>>  * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
>>  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>>  *
>>  * This code is free software; you can redistribute it and/or modify it
>>  * under the terms of the GNU General Public License version 2 only, as
>>  * published by the Free Software Foundation.
>>  *
>>  * This code is distributed in the hope that it will be useful, but WITHOUT
>>  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
>>  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
>>  * version 2 for more details (a copy is included in the LICENSE file that
>>  * accompanied this code).
>>  *
>>  * You should have received a copy of the GNU General Public License version
>>  * 2 along with this work; if not, write to the Free Software Foundation,
>>  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
>>  *
>>  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
>>  * or visit www.oracle.com if you need additional information or have any
>>  * questions.
>>  */
>> 
>> /*
>>  * @test
>>  * @bug 9999999
>>  * @summary XXX
>>  * @run main/othervm --limit-modules jdk.compiler MarkdownTransformerPositionTest
>>  * @run main MarkdownTransformerPositionTest
>>  */
>> 
>> import com.sun.source.doctree.DocCommentTree;
>> import com.sun.source.doctree.RawTextTree;
>> import com.sun.source.tree.*;
>> import com.sun.source.util.*;
>> 
>> import java.net.URI;
>> import java.util.*;
>> import javax.lang.model.element.Element;
>> import javax.tools.*;
>> 
>> 
>> public class MarkdownTransformerPositionTest {
>> 
>>     public static void main(String... args) throws Exception {
>>         String source = """
>>                         /// Markdown test
>>                         ///
>>                         /// @author testAuthor
>>                         public class Test {
>>         ...
>
> Uugh.  Noted.

There are two cases that need consideration:
1. A tree that is not modified during the transformation, as in the test case here, so that all nodes should be "as before"
2. A tree that is modified during the transformation, raising the issue of the positions of the new node and any enclosing node

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

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