[23] Update Elements#getDocComment() to support markdown #3189 (#3221)

#3221

org.eclipse.jdt.compiler.apt.tests/processors8/org/eclipse/jdt/compiler/apt/tests/processors/elements/Java23ElementProcessor.java

@@ -133,13 +133,23 @@ public void testJavadocKind1() throws IOException {
 		assertNotNull("method element should not be null", method);
 		kind = _elementUtils.getDocCommentKind(method);
 		assertSame("Incorrect doc kind", DocCommentKind.END_OF_LINE, kind);
+		String docComment = _elementUtils.getDocComment(method);
+		assertEquals("Incorrect doc comment", 
+				"\n/A markdown type comment on a method - line 1\n"
+				+ "//// A markdown type comment on a method - line 2\n"
+				+ "    A markdown type comment on a method - line 3\n", docComment);
 	}
 	public void testJavadocKind2() throws IOException {
 		String typeName = "my.mod.Main2";
 		TypeElement typeElement = _elementUtils.getTypeElement(typeName);
 		assertNotNull("type element should not be null", typeElement);
 		DocCommentKind kind = _elementUtils.getDocCommentKind(typeElement);
 		assertSame("Incorrect doc kind", DocCommentKind.END_OF_LINE, kind);
+		String docComment = _elementUtils.getDocComment(typeElement);
+		assertEquals("Incorrect doc comment",
+				"\n/A markdown type comment on a class - line 1\n"
+				+ "//// A markdown type comment on a class - line 2\n"
+				+ "    A markdown type comment on a class - line 3\n", docComment);
 		List<? extends Element> enclosedElements = typeElement.getEnclosedElements();
 		ExecutableElement method = null;
 		for (Element element : enclosedElements) {
@@ -151,6 +161,50 @@ public void testJavadocKind2() throws IOException {
 		kind = _elementUtils.getDocCommentKind(method);
 		assertSame("Incorrect doc kind", DocCommentKind.TRADITIONAL, kind);
 	}
+	public void testMarkdownContent3() throws IOException {
+		String typeName = "my.mod.Main1";
+		TypeElement typeElement = _elementUtils.getTypeElement(typeName);
+		assertNotNull("type element should not be null", typeElement);
+		List<? extends Element> enclosedElements = typeElement.getEnclosedElements();
+		ExecutableElement foo1 = null;
+		ExecutableElement foo2 = null;
+		ExecutableElement foo3 = null;
+		ExecutableElement foo4 = null;
+		for (Element element : enclosedElements) {
+			switch(element.getSimpleName().toString()) {
+				case "foo1": 
+					foo1 = (ExecutableElement) element;
+				case "foo2": 
+					foo2 = (ExecutableElement) element;
+				case "foo3": 
+					foo3 = (ExecutableElement) element;
+				case "foo4": 
+					foo4 = (ExecutableElement) element;
+				default: break;
+			}
+		}
+		String docComment = _elementUtils.getDocComment(foo1);
+		assertEquals("Incorrect doc comment", 
+				"Doc comment with 3 lines\n"
+				+ "\n"
+				+ "with an empty line in the middle", docComment);
+		docComment = _elementUtils.getDocComment(foo2);
+		assertEquals("Incorrect doc comment", 
+				"This is the actual doc commment.", docComment);
+		docComment = _elementUtils.getDocComment(foo3);
+		assertEquals("Incorrect doc comment", 
+				  "| Code  | Color |\n"
+				+ "|-------|-------|\n"
+				+ "| R     | Red   |\n"
+				+ "| G     | Green |\n"
+				+ "| B     | Blue  |", docComment);
+		docComment = _elementUtils.getDocComment(foo4);
+		assertEquals("Incorrect doc comment", 
+				  "{@inheritDoc}\n"
+				+ "Get the inherited function.\n"
+				+ "\n"
+				+ "@param p parameter", docComment);
+	}
 
 	@Override
 	public void reportError(String msg) {
@@ -167,6 +221,28 @@ private String getExceptionStackTrace(Throwable t) {
 		}
 		return buf.toString();
 	}
+    public void assertEquals(String message, Object expected, Object actual) {
+        if (equalsRegardingNull(expected, actual)) {
+            return;
+        } else {
+        	reportError(message + ", expected " + expected.toString() + " but was " + actual.toString());
+        }
+    }
+
+    public void assertEquals(String message, Object expected, Object alternateExpected, Object actual) {
+        if (equalsRegardingNull(expected, actual) || equalsRegardingNull(alternateExpected, actual)) {
+            return;
+        } else {
+        	reportError(message + ", expected " + expected.toString() + " but was " + actual.toString());
+        }
+    }
+
+    static boolean equalsRegardingNull(Object expected, Object actual) {
+        if (expected == null) {
+            return actual == null;
+        }
+        return expected.equals(actual);
+    }
 	public void assertSame(String msg, Object obj1, Object obj2) {
 		if (obj1 != obj2) {
 			reportError(msg + ", should be " + obj1.toString() + " but " + obj2.toString());

org.eclipse.jdt.compiler.apt.tests/resources/mod_locations/modules23/module.main/my/mod/Main1.java

@@ -5,8 +5,33 @@
  */
 public class Main1 {
 	///
-	/// A markdown type comment on a method
+	////A markdown type comment on a method - line 1
+	/////// A markdown type comment on a method - line 2
+	///    A markdown type comment on a method - line 3
 	///
     public static void myMethod(String argv[]) {
     }
+    /// Doc comment with 3 lines
+    ///
+    /// with an empty line in the middle
+    public void foo1() {}
+    /// Dangling comment, not considered
+
+    /// This is the actual doc commment.
+    public void foo2() {}
+
+    /// | Code  | Color |
+    /// |-------|-------|
+    /// | R     | Red   |
+    /// | G     | Green |
+    /// | B     | Blue  |
+    public void foo3(){
+    }
+
+    /// {@inheritDoc}
+    /// Get the inherited function.
+    ///
+    /// @param p parameter
+    public void foo4(int p){
+    }
 }

org.eclipse.jdt.compiler.apt.tests/resources/mod_locations/modules23/module.main/my/mod/Main2.java

@@ -1,7 +1,9 @@
 package my.mod;
 
 ///
-/// A markdown type comment on a class
+////A markdown type comment on a class - line 1
+/////// A markdown type comment on a class - line 2
+///    A markdown type comment on a class - line 3
 ///
 public class Main2 {
 	/**

org.eclipse.jdt.compiler.apt.tests/src/org/eclipse/jdt/compiler/apt/tests/Java23ElementsTests.java

@@ -46,6 +46,14 @@ public void testJavadocKind2Javac() throws IOException {
 		JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
 		internalTestWithBinary(compiler, MODULE_PROC, "23", "testJavadocKind2", null, "modules23", false);
 	}
+	public void testMarkdownContent3() throws IOException {
+		JavaCompiler compiler = BatchTestUtils.getEclipseCompiler();
+		internalTestWithBinary(compiler, MODULE_PROC, "23", "testMarkdownContent3", null, "modules23", false);
+	}
+	public void testMarkdownContent3Javac() throws IOException {
+		JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
+		internalTestWithBinary(compiler, MODULE_PROC, "23", "testMarkdownContent3", null, "modules23", false);
+	}
 	@SuppressWarnings({ "rawtypes", "unchecked" })
 	protected void internalTestWithBinary(JavaCompiler compiler, String processor, String compliance, String testMethod, String testClass, String resourceArea,
 				boolean processBinariesAgain) throws IOException {

org.eclipse.jdt.compiler.tool.tests/.classpath

@@ -12,6 +12,6 @@
 			<attribute name="test" value="true"/>
 		</attributes>
 	</classpathentry>
-	<classpathentry kind="lib" path="lib/javax18api.jar"/>
+	<classpathentry kind="lib" path="lib/javax23api.jar"/>
 	<classpathentry kind="output" path="bin"/>
 </classpath>

org.eclipse.jdt.compiler.tool.tests/build.properties

@@ -22,4 +22,4 @@ bin.includes = META-INF/,\
 src.includes = about.html
 source.. = src/
 output.. = bin/
-jars.extra.classpath = lib/javax18api.jar
+jars.extra.classpath = lib/javax23api.jar

org.eclipse.jdt.compiler.tool.tests/src/org/eclipse/jdt/compiler/tool/tests/ForwardingStandardJavaFileManager.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2008, 2017 IBM Corporation and others.
+ * Copyright (c) 2008, 2024 IBM Corporation and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -72,6 +72,7 @@ public Iterable<? extends JavaFileObject> getJavaFileObjects(Path... arg0) {
 	}
 
 	@Override
+	@Deprecated // method from StandardJavaFileManager is deprecated
 	public Iterable<? extends JavaFileObject> getJavaFileObjectsFromPaths(Iterable<? extends Path> arg0) {
 		return this.fileManager.getJavaFileObjectsFromPaths(arg0);
 	}

org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/internal/compiler/apt/model/ElementsImpl.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2023 BEA Systems, Inc. and others
+ * Copyright (c) 2006, 2024 BEA Systems, Inc. and others
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -388,7 +388,8 @@ protected char[] getUnparsedDocComment(Element e)
 		if (javadoc != null && referenceContext != null) {
 			char[] contents = referenceContext.compilationResult().getCompilationUnit().getContents();
 			if (contents != null) {
-				return CharOperation.subarray(contents, javadoc.sourceStart, javadoc.sourceEnd - 1);
+				// In case of markdown, the end of line is part of the source range
+				return CharOperation.subarray(contents, javadoc.sourceStart, javadoc.isMarkdown ? javadoc.sourceEnd : javadoc.sourceEnd - 1);
 			}
 		}
 		return null;

org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/internal/compiler/apt/model/ElementsImpl9.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2023 BEA Systems, Inc. and others
+ * Copyright (c) 2006, 2024 BEA Systems, Inc. and others
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -37,9 +37,11 @@
 import org.eclipse.jdt.internal.compiler.apt.dispatch.BaseProcessingEnvImpl;
 import org.eclipse.jdt.internal.compiler.impl.ReferenceContext;
 import org.eclipse.jdt.internal.compiler.lookup.*;
+import org.eclipse.jdt.internal.compiler.parser.ScannerHelper;
 import org.eclipse.jdt.internal.compiler.tool.EclipseFileManager;
 import org.eclipse.jdt.internal.compiler.tool.PathFileObject;
 import org.eclipse.jdt.internal.compiler.util.HashtableOfModule;
+import org.eclipse.jdt.internal.compiler.util.TextBlockUtil;
 
 /**
  * Utilities for working with java9 language elements.
@@ -292,8 +294,54 @@ public boolean isCompactConstructor(ExecutableElement e) {
         return methodBinding.isCompactConstructor();
     }
 	@Override
+	public String getDocComment(Element e) {
+		DocCommentKind kind = getDocCommentKind(e);
+		if (kind == null)
+			return null;
+		if (kind == DocCommentKind.TRADITIONAL) {
+			return super.getDocComment(e);
+		}
+		// 1. Get the unparsed document content and convert it to individual lines
+		// 2. Remove the /// from each line
+		// 3. Common whitespace after /// in each line is removed
+		// 4. The lines are put together with \n as delimiter and returned
+		char[] unparsed = getUnparsedDocComment(e);
+		char[][] lines = TextBlockUtil.convertTextBlockToLines(unparsed);
+		char[][] contentLines = new char[lines.length][];
+		for (int i = 0; i < lines.length; i++) {
+			char[] cs = lines[i];
+			int slashes = 0;
+			int startIdx = 0;
+			line: for (char c : cs) {
+				startIdx++;
+				switch(c) {
+					case '/':
+						slashes++;
+						if (slashes > 2)
+							break line;
+						break;
+					default:
+						if (!ScannerHelper.isWhitespace(c) || slashes == 3) {
+							break line;
+						}
+						break;
+				}
+			}
+			char[] cs2 = new char[cs.length - startIdx];
+			contentLines[i] = cs2;
+			System.arraycopy(cs, startIdx, cs2, 0, cs2.length);
+		}
+		int textBlockIndent = TextBlockUtil.getWhitespacePrefix(contentLines);
+		char[] formatTextBlock = TextBlockUtil.formatTextBlock(contentLines, textBlockIndent);
+		StringBuilder sb = new StringBuilder();
+		sb.append(formatTextBlock);
+		return sb.toString();
+	}
+	@Override
     public DocCommentKind getDocCommentKind(Element e) {
 		char[] unparsed = getUnparsedDocComment(e);
+		if (unparsed == null)
+			return null;
 		String[] lines = new String(unparsed).split("\n"); //$NON-NLS-1$
 		Matcher delimiterMatcher = INITIAL_DELIMITER.matcher(lines[0]);
 		return (delimiterMatcher.find()) ? DocCommentKind.TRADITIONAL : DocCommentKind.END_OF_LINE;