Add support for inline tags within an inlined return

- modify AbstractCommentParser to keep track when we are in an
  inlined return statement and to add inline tags as fragments
- add addFragmentToInlineReturn() method
- add new test to JavadocTest_16
- fixes eclipse-jdt#1026

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

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2022 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
@@ -90,6 +90,7 @@ public abstract class AbstractCommentParser implements JavadocTagConstants {
 	// Flags
 	protected boolean lineStarted = false;
 	protected boolean inlineTagStarted = false;
+	protected boolean inlineReturn= false;
 	protected boolean abort = false;
 	protected int kind;
 	protected int tagValue = NO_TAG_VALUE;
@@ -251,7 +252,7 @@ protected boolean commentParse() {
 								openingBraces = 0;
 							}
 						} else if ((!this.lineStarted || previousChar == '{') || lookForTagsInSnippets()) {
-							if (this.inlineTagStarted) {
+							if (this.inlineTagStarted && !inlineReturn) {
 								setInlineTagStarted(false);
 								// bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=53279
 								// Cannot have @ inside inline comment
@@ -352,6 +353,9 @@ protected boolean commentParse() {
 							if (!isFormatterParser && !considerTagAsPlainText)
 								this.textStart = this.index;
 							setInlineTagStarted(false);
+							if (this.inlineReturn) {
+								addFragmentToInlineReturn();
+							}
 						} else {
 							if (!this.lineStarted) {
 								this.textStart = previousPosition;
@@ -368,23 +372,26 @@ protected boolean commentParse() {
 						if (considerTagAsPlainText) {
 							openingBraces++;
 						} else if (this.inlineTagStarted) {
+							if (this.tagValue == TAG_RETURN_VALUE) {
+								this.inlineReturn= true;
+							}
+							if (this.lineStarted && this.textStart != -1 && this.textStart < textEndPosition) {
+								pushText(this.textStart, textEndPosition);
+							}
 							setInlineTagStarted(false);
 							// bug https://bugs.eclipse.org/bugs/show_bug.cgi?id=53279
 							// Cannot have opening brace in inline comment
-							if (this.reportProblems) {
+							if (this.reportProblems && !this.inlineReturn || peekChar() != '@') {
 								int end = previousPosition<invalidInlineTagLineEnd ? previousPosition : invalidInlineTagLineEnd;
 								this.sourceParser.problemReporter().javadocUnterminatedInlineTag(this.inlineTagStart, end);
 							}
-							if (this.lineStarted && this.textStart != -1 && this.textStart < textEndPosition) {
-								pushText(this.textStart, textEndPosition);
-							}
 							refreshInlineTagPosition(textEndPosition);
 							textEndPosition = this.index;
 						} else if (peekChar() != '@') {
 							if (this.textStart == -1) this.textStart = previousPosition;
 							textEndPosition = this.index;
 						}
-						if (!this.lineStarted) {
+						if (!this.lineStarted && !inlineReturn) {
 							this.textStart = previousPosition;
 						}
 						this.lineStarted = true;
@@ -481,6 +488,10 @@ protected boolean commentParse() {
 		return validComment;
 	}
 
+	protected void addFragmentToInlineReturn() {
+		// do nothing
+	}
+
 	protected void consumeToken() {
 		this.currentTokenType = -1; // flush token cache
 		updateLineEnd();

org.eclipse.jdt.core.tests.compiler/src/org/eclipse/jdt/core/tests/compiler/regression/JavadocTest_16.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2023 Andrey Loskutov ([email protected]) and others.
+ * Copyright (c) 2023, 2024 Andrey Loskutov ([email protected]) and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -144,7 +144,26 @@ public int sample() {
 		}
 	);
 }
-
+public void testInlineReturn3() {
+	if(this.complianceLevel < ClassFileConstants.JDK16) {
+		return;
+	}
+	this.runConformTest(
+		new String[] {
+			"X.java",
+			"""
+			public class X {
+				/** {@return {@code true} or else
+				 *  {@code false}}
+				 */
+				public boolean sample() {
+					return false;
+				}
+			}
+			""",
+		}
+	);
+}
 public void testInlineReturn_broken1() {
 	if(this.complianceLevel < ClassFileConstants.JDK16) {
 		return;

org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/DocCommentParser.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2004, 2022 IBM Corporation and others.
+ * Copyright (c) 2004, 2024 IBM Corporation and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -1290,6 +1290,29 @@ protected void refreshInlineTagPosition(int previousPosition) {
 		}
 	}
 
+	@Override
+	protected void addFragmentToInlineReturn() {
+		TagElement currTag= (TagElement) this.astStack[this.astPtr];
+		List fragments= currTag.fragments();
+		int size= fragments.size();
+		if (size > 1) {
+			ASTNode lastNode= (ASTNode) fragments.get(size - 1);
+			if (lastNode instanceof TagElement lastTag) {
+				if (!lastTag.getTagName().equals(TagElement.TAG_RETURN)) {
+					ASTNode secondLastNode= (ASTNode) fragments.get(size - 2);
+					if (secondLastNode instanceof TagElement prevTag && prevTag.getTagName().equals(TagElement.TAG_RETURN)) {
+						fragments.remove(size - 1);
+						prevTag.fragments().add(lastNode);
+						this.inlineTagStart= prevTag.getStartPosition();
+						this.inlineTagStarted= true;
+						prevTag.setSourceRange(prevTag.getStartPosition(), lastNode.getStartPosition() + lastNode.getLength() - prevTag.getStartPosition());
+					}
+				} else {
+					this.inlineReturn= false;
+				}
+			}
+		}
+	}
 	/*
 	 * Add stored tag elements to associated comment.
 	 */