[23] JEP 467 - Compiler changes for supporting markdown Javadoc comments

org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/internal/compiler/impl/JavaFeature.java

@@ -114,6 +114,10 @@ public enum JavaFeature {
 			Messages.bind(Messages.module_imports),
 			CharOperation.NO_CHAR_CHAR,
 			true),
+	MARKDOWN_COMMENTS(ClassFileConstants.JDK23,
+			Messages.bind(Messages.markdown_comments),
+			CharOperation.NO_CHAR_CHAR,
+			true),
     ;
 
 	final long compliance;

org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/internal/compiler/parser/AbstractCommentParser.java

@@ -8,6 +8,10 @@
  *
  * SPDX-License-Identifier: EPL-2.0
  *
+ * This is an implementation of an early-draft specification developed under the Java
+ * Community Process (JCP) and is made available for testing and evaluation purposes
+ * only. The code is not compatible with any specification of the JCP.
+ *
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
@@ -88,6 +92,7 @@ public abstract class AbstractCommentParser implements JavadocTagConstants {
 	protected int[] lineEnds;
 
 	// Flags
+	protected boolean markdown = false;
 	protected boolean lineStarted = false;
 	protected boolean inlineTagStarted = false;
 	protected boolean inlineReturn= false;
@@ -187,10 +192,13 @@ protected boolean commentParse() {
 			}
 			int previousPosition = this.index;
 			char nextCharacter = 0;
+			this.markdown = this.source[this.javadocStart + 1] == '/';
 			if (realStart == this.javadocStart) {
-				nextCharacter = readChar(); // second '*'
-				while (peekChar() == '*') {
-					nextCharacter = readChar(); // read all contiguous '*'
+				nextCharacter = readChar(); // second '*' or '/'
+				if (!this.markdown) {
+					while (peekChar() == '*') {
+						nextCharacter = readChar(); // read all contiguous '*'
+					}
 				}
 				this.javadocTextStart = this.index;
 			}
@@ -398,25 +406,6 @@ protected boolean commentParse() {
 						// https://bugs.eclipse.org/bugs/show_bug.cgi?id=206345: do not update tag start position when ignoring tags
 						if (!considerTagAsPlainText) this.inlineTagStart = previousPosition;
 						break;
-					case '*' :
-						// Store the star position as text start while formatting
-						lastStarPosition = previousPosition;
-						if (previousChar != '*') {
-							this.starPosition = previousPosition;
-							if (isDomParser || isFormatterParser) {
-								if (lineHasStar) {
-									this.lineStarted = true;
-									if (this.textStart == -1) {
-										this.textStart = previousPosition;
-										if (this.index <= this.javadocTextEnd) textEndPosition = this.index;
-									}
-								}
-								if (!this.lineStarted) {
-									lineHasStar = true;
-								}
-							}
-						}
-						break;
 					case '\u000c' :	/* FORM FEED               */
 					case ' ' :			/* SPACE                   */
 					case '\t' :			/* HORIZONTAL TABULATION   */
@@ -429,13 +418,42 @@ protected boolean commentParse() {
 							textEndPosition = this.index;
 						}
 						break;
+					case '*' :
+						// Store the star position as text start while formatting
+						if (!this.markdown) {
+							lastStarPosition = previousPosition;
+							if (previousChar != '*') {
+								this.starPosition = previousPosition;
+								if (isDomParser || isFormatterParser) {
+									if (lineHasStar) {
+										this.lineStarted = true;
+										if (this.textStart == -1) {
+											this.textStart = previousPosition;
+											if (this.index <= this.javadocTextEnd) textEndPosition = this.index;
+										}
+									}
+									if (!this.lineStarted) {
+										lineHasStar = true;
+									}
+								}
+							}
+							break;
+						}
+						//$FALL-THROUGH$
 					case '/':
-						if (previousChar == '*') {
+						if (this.markdown) {
+							if (nextCharacter != '*') // fall-through
+								break;
+						} else if (previousChar == '*') {
 							// End of javadoc
 							break;
 						}
 						// $FALL-THROUGH$ - fall through default case
 					default :
+						if (this.markdown && nextCharacter == '[') {
+							if (parseMarkdownLinks())
+								break;
+						}
 						if (isFormatterParser && nextCharacter == '<') {
 							// html tags are meaningful for formatter parser
 							int initialIndex = this.index;
@@ -2956,6 +2974,10 @@ private boolean containsNewLine(String str) {
 		return consider;
 	}
 
+	/*
+	 * Parse markdown links that are replacing @link and @linkplain
+	 */
+	protected abstract boolean parseMarkdownLinks() throws InvalidInputException;
 	/*
 	 * Parse tag declaration
 	 */
@@ -3442,6 +3464,11 @@ protected boolean verifySpaceOrEndComment() {
 		// Whitespace or inline tag closing brace
 		char ch = peekChar();
 		switch (ch) {
+			case ']':
+				// TODO: Check if we need to exclude escaped ]
+				if (this.markdown)
+					return true;
+				break;
 			case '}':
 				return this.inlineTagStarted;
 			default:

org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/internal/compiler/parser/JavadocParser.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2023 IBM Corporation and others.
+ * Copyright (c) 2000, 2024 IBM Corporation and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -8,6 +8,10 @@
  *
  * SPDX-License-Identifier: EPL-2.0
  *
+ * This is an implementation of an early-draft specification developed under the Java
+ * Community Process (JCP) and is made available for testing and evaluation purposes
+ * only. The code is not compatible with any specification of the JCP.
+ *
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
@@ -123,6 +127,7 @@ public boolean checkDeprecation(int commentPtr) {
 		try {
 			this.source = this.sourceParser.scanner.source;
 			this.scanner.setSource(this.source); // updating source in scanner
+			this.markdown = this.source[this.javadocStart + 1] == '/';
 			if (this.checkDocComment) {
 				// Initialization
 				this.scanner.lineEnds = this.sourceParser.scanner.lineEnds;
@@ -150,6 +155,11 @@ public boolean checkDeprecation(int commentPtr) {
 					nextCharacter : while (this.index < this.lineEnd) {
 						char c = readChar(); // consider unicodes
 						switch (c) {
+							case '/' :
+								if (!this.markdown) {
+									break;
+								}
+								//$FALL-THROUGH$
 							case '*' :
 							case '\u000c' :	/* FORM FEED               */
 							case ' ' :			/* SPACE                   */
@@ -560,7 +570,54 @@ protected void parseSimpleTag() {
 				break;
 		}
 	}
-
+	@Override
+	protected boolean parseMarkdownLinks() throws InvalidInputException {
+		boolean valid = false;
+		// The markdown links can come in single [] or pair of [] with no space between them
+		// We are here after we have seen [
+		// Look for closing ] and then an option [
+		// immediately without any other characters, including whitespace
+		// If there are two [], then the first one becomes the link text
+		// and the second one is the reference
+		// in case of just one [], then that is the reference
+		int start = this.index;
+		char currentChar = readChar();
+		loop: while (this.index < this.scanner.eofPosition) {
+			switch(currentChar) {
+				case '\\':
+					char c = peekChar();
+					if (c == '[' || c == ']') {
+						readChar();
+					}
+					break;
+				case ']':
+					if (peekChar() == '[') {
+						// We might want to store the description in case of DOM parser
+						// but the compiler does not need it
+						//int length = this.index - start - 1;
+						//System.arraycopy(this.scanner.source, start, desc = new char[length], 0, length);
+						// move it past '['
+						currentChar = readChar();
+						start = this.index;
+					} else {
+						int eofBkup = this.scanner.eofPosition;
+						this.scanner.eofPosition = this.index - 1;
+						this.scanner.resetTo(start, this.javadocEnd);
+						valid = parseReference(true);
+						this.scanner.eofPosition = eofBkup;
+						break loop;
+					}
+					break;
+				case '\r':
+				case '\n':
+					return false;
+				default:
+					break;
+			}
+			currentChar = readChar();
+		}
+		return valid;
+	}
 	@Override
 	protected boolean parseTag(int previousPosition) throws InvalidInputException {