From e1428a7fa73999aba0e0f390e1c0d66d7c6acbe8 Mon Sep 17 00:00:00 2001
From: Suby S Surendran <suby.surendran@ibm.com>
Date: Mon, 29 Dec 2025 14:54:57 +0530
Subject: [PATCH] Incorrect Javadoc rendering when inline @ tokens appear in
 block tags

Fix incorrect Javadoc list rendering when inline @ tokens appear in
block tags

Fix: https://github.com/eclipse-jdtls/eclipse.jdt.ls/issues/3631
---
 .../javadoc/AbstractJavaDocConverter.java     | 41 ++++++++++++-------
 .../internal/handlers/HoverHandlerTest.java   | 26 ++++++++++++
 2 files changed, 53 insertions(+), 14 deletions(-)

diff --git a/org.eclipse.jdt.ls.core/src/org/eclipse/jdt/ls/core/internal/javadoc/AbstractJavaDocConverter.java b/org.eclipse.jdt.ls.core/src/org/eclipse/jdt/ls/core/internal/javadoc/AbstractJavaDocConverter.java
index 53eb9bcbe5..49f3b3fdd0 100644
--- a/org.eclipse.jdt.ls.core/src/org/eclipse/jdt/ls/core/internal/javadoc/AbstractJavaDocConverter.java
+++ b/org.eclipse.jdt.ls.core/src/org/eclipse/jdt/ls/core/internal/javadoc/AbstractJavaDocConverter.java
@@ -189,19 +189,27 @@ protected void print(StringBuilder buffer, String tag, String content) {
 		@Override
 		protected void printRest(StringBuilder buffer, List<Pair> rest) {
 			if (!rest.isEmpty()) {
-				Iterator<Pair> e = rest.iterator();
-				while (e.hasNext()) {
-					Pair p = e.next();
-					buffer.append("<li>"); //$NON-NLS-1$
-					if (p.fTag() != null) {
+				if (rest.size() == 1) {
+					Iterator<Pair> e = rest.iterator();
+					if (e.hasNext()) {
+						Pair p = e.next();
 						buffer.append(p.fTag());
 					}
-					if (p.fContent() != null) {
-						buffer.append("<ul><li>"); //$NON-NLS-1$
-						buffer.append(p.fContent());
-						buffer.append("</li></ul>"); //$NON-NLS-1$
+				} else {
+					Iterator<Pair> e = rest.iterator();
+					while (e.hasNext()) {
+						Pair p = e.next();
+						buffer.append("<li>"); //$NON-NLS-1$
+						if (p.fTag() != null) {
+							buffer.append(p.fTag());
+						}
+						if (p.fContent() != null) {
+							buffer.append("<ul><li>"); //$NON-NLS-1$
+							buffer.append(p.fContent());
+							buffer.append("</li></ul>"); //$NON-NLS-1$
+						}
+						buffer.append("</li>"); //$NON-NLS-1$
 					}
-					buffer.append("</li>"); //$NON-NLS-1$
 				}
 			}
 		}
@@ -209,10 +217,15 @@ protected void printRest(StringBuilder buffer, List<Pair> rest) {
 		@Override
 		protected String printSimpleTag(List<Pair> rest) {
 			StringBuilder buffer = new StringBuilder();
-			buffer.append("<ul>"); //$NON-NLS-1$
-			printTagAttributes(buffer);
-			printRest(buffer, rest);
-			buffer.append("</ul>"); //$NON-NLS-1$
+			if (rest.size() == 1) {
+				printTagAttributes(buffer);
+				printRest(buffer, rest);
+			} else {
+				buffer.append("<ul>"); //$NON-NLS-1$
+				printTagAttributes(buffer);
+				printRest(buffer, rest);
+				buffer.append("</ul>"); //$NON-NLS-1$
+			}
 			return buffer.toString();
 		}
 	}
diff --git a/org.eclipse.jdt.ls.tests/src/org/eclipse/jdt/ls/core/internal/handlers/HoverHandlerTest.java b/org.eclipse.jdt.ls.tests/src/org/eclipse/jdt/ls/core/internal/handlers/HoverHandlerTest.java
index b8c07c5e71..4d8244fb5f 100644
--- a/org.eclipse.jdt.ls.tests/src/org/eclipse/jdt/ls/core/internal/handlers/HoverHandlerTest.java
+++ b/org.eclipse.jdt.ls.tests/src/org/eclipse/jdt/ls/core/internal/handlers/HoverHandlerTest.java
@@ -1050,4 +1050,30 @@ public class Meh {}
 		actual = ResourceUtils.dos2Unix(actual);
 		assertEquals(expectedJavadoc, actual, "Unexpected hover ");
 	}
+
+	@Test
+	public void testIncorrectJavadocRendering_3649() throws Exception {
+		IPackageFragment pack1 = sourceFolder.createPackageFragment("test1", false, null);
+		String content = """
+				package test1;
+				/**
+				  * Some javadoc and then ...
+				  * @jls 9.6.4.1 @Target
+				  */
+				public class Hover {}
+				""";
+		ICompilationUnit cu = pack1.createCompilationUnit("Hover.java", content, false, null);
+		Hover hover = getHover(cu, 5, 14);
+		assertNotNull(hover);
+		assertEquals(2, hover.getContents().getLeft().size());
+
+		//@formatter:off
+		String expectedJavadoc = "Some javadoc and then ...\n"
+				+ "\n"
+				+ "* **@jls**\n"
+				+ "  * 9.6.4.1 @Target";
+		String actual = hover.getContents().getLeft().get(1).getLeft();
+		actual = ResourceUtils.dos2Unix(actual);
+		assertEquals(expectedJavadoc, actual, "Unexpected hover ");
+	}
 }