On Tue, 6 Feb 2024 01:36:58 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
>> Please review a patch to add support for Markdown syntax in documentation >> comments, as described in the associated JEP. >> >> Notable features: >> >> * support for `///` documentation comments in `JavaTokenizer` >> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` >> library >> * updates to `DocCommentParser` to treat `///` comments as Markdown >> * updates to the standard doclet to render Markdown comments in HTML > > Jonathan Gibbons has updated the pull request incrementally with one > additional commit since the last revision: > > First pass at remove DocCommentTransformer from the public API. > > It is still declared internally, and installed by default, using the > service-provider mechanism. > If the standard impl is not available, an identity transformer is used. 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 { } """; JavaCompiler comp = ToolProvider.getSystemJavaCompiler(); JavacTask task = (JavacTask)comp.getTask(null, null, null, null, null, Arrays.asList(new JavaSource(source))); CompilationUnitTree cu = task.parse().iterator().next(); task.analyze(); DocTrees trees = DocTrees.instance(task); List<String> rawSpans = new ArrayList<>(); TreePath clazzTP = new TreePath(new TreePath(cu), cu.getTypeDecls().get(0)); Element clazz = trees.getElement(clazzTP); DocCommentTree docComment = trees.getDocCommentTree(clazz); new DocTreeScanner<Void, Void>() { @Override public Void visitRawText(RawTextTree node, Void p) { int start = (int) trees.getSourcePositions().getStartPosition(cu, docComment, node); int end = (int) trees.getSourcePositions().getEndPosition(cu, docComment, node); rawSpans.add(source.substring(start, end)); return super.visitRawText(node, p); } }.scan(docComment, null); List<String> expectedRawSpans = List.of("Markdown test", "testAuthor"); if (!expectedRawSpans.equals(rawSpans)) { throw new AssertionError("Incorrect raw text spans, should be: " + expectedRawSpans + ", but is: " + rawSpans); } System.err.println("Test result: success, boot modules: " + ModuleLayer.boot().modules()); } static class JavaSource extends SimpleJavaFileObject { private final String source; public JavaSource(String source) { super(URI.create("myfo:/Test.java"), JavaFileObject.Kind.SOURCE); this.source = source; } @Override public CharSequence getCharContent(boolean ignoreEncodingErrors) { return source; } } } ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1479306878