diff --git a/java/java-analysis-impl/resources/messages/InspectionGadgetsBundle.properties b/java/java-analysis-impl/resources/messages/InspectionGadgetsBundle.properties
index e6a27416061e..935758e5f456 100644
--- a/java/java-analysis-impl/resources/messages/InspectionGadgetsBundle.properties
+++ b/java/java-analysis-impl/resources/messages/InspectionGadgetsBundle.properties
@@ -2365,6 +2365,9 @@ inspection.deconstruction.can.be.used.display.name=Record pattern can be used
inspection.deconstruction.can.be.used.message=Can be replaced with record pattern
inspection.deconstruction.can.be.used.fix.family.name=Replace with record pattern
+markdown.documentation.comments.migration.display.name=Javadoc comment can be Markdown documentation comment
+markdown.documentation.comments.migration.fix=Convert to Markdown documentation comment
+
array.hash.code.fix.family.name=Replace with 'Arrays.hashCode()' call
objects.hash.fix.family.name=Wrap with 'Arrays.hashCode()'
unqualified.static.access.fix.family.name=Qualify static access
diff --git a/java/java-analysis-impl/src/com/siyeh/ig/migration/MarkdownDocumentationCommentsMigrationInspection.java b/java/java-analysis-impl/src/com/siyeh/ig/migration/MarkdownDocumentationCommentsMigrationInspection.java
new file mode 100644
index 000000000000..899600641802
--- /dev/null
+++ b/java/java-analysis-impl/src/com/siyeh/ig/migration/MarkdownDocumentationCommentsMigrationInspection.java
@@ -0,0 +1,309 @@
+// Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
+package com.siyeh.ig.migration;
+
+import com.intellij.codeInspection.LocalQuickFix;
+import com.intellij.modcommand.ModPsiUpdater;
+import com.intellij.modcommand.PsiUpdateModCommandQuickFix;
+import com.intellij.openapi.editor.Document;
+import com.intellij.openapi.project.Project;
+import com.intellij.psi.JavaDocTokenType;
+import com.intellij.psi.PsiElement;
+import com.intellij.psi.PsiWhiteSpace;
+import com.intellij.psi.impl.source.javadoc.PsiDocMethodOrFieldRef;
+import com.intellij.psi.javadoc.*;
+import com.intellij.psi.tree.IElementType;
+import com.intellij.psi.tree.TokenSet;
+import com.intellij.psi.util.PsiTreeUtil;
+import com.siyeh.InspectionGadgetsBundle;
+import com.siyeh.ig.BaseInspection;
+import com.siyeh.ig.BaseInspectionVisitor;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * @author Bas Leijdekkers
+ */
+final class MarkdownDocumentationCommentsMigrationInspection extends BaseInspection {
+ @Override
+ protected @NotNull String buildErrorString(Object... infos) {
+ return InspectionGadgetsBundle.message("markdown.documentation.comments.migration.display.name");
+ }
+
+ @Override
+ protected @NotNull LocalQuickFix buildFix(Object... infos) {
+ return new MarkdownDocumentationCommentsMigrationFix();
+ }
+
+ @Override
+ public BaseInspectionVisitor buildVisitor() {
+ return new MarkdownDocumentationCommentsMigrationVisitor();
+ }
+
+ private static class MarkdownDocumentationCommentsMigrationVisitor extends BaseInspectionVisitor {
+ @Override
+ public void visitDocComment(@NotNull PsiDocComment comment) {
+ super.visitDocComment(comment);
+ PsiElement child = comment.getFirstChild();
+ if (!"/**".equals(child.getText())) {
+ return;
+ }
+ registerError(isVisibleHighlight(comment) ? child : comment);
+ }
+ }
+
+ private static class MarkdownDocumentationCommentsMigrationFix extends PsiUpdateModCommandQuickFix {
+
+ public static final TokenSet SKIP_TOKENS = TokenSet.create(JavaDocTokenType.DOC_COMMENT_START, JavaDocTokenType.DOC_COMMENT_END);
+
+ @Override
+ public @NotNull String getFamilyName() {
+ return InspectionGadgetsBundle.message("markdown.documentation.comments.migration.fix");
+ }
+
+ @Override
+ protected void applyFix(@NotNull Project project, @NotNull PsiElement element, @NotNull ModPsiUpdater updater) {
+ if (element instanceof PsiDocToken) element = element.getParent();
+ if (!(element instanceof PsiDocComment)) return;
+ StringBuilder text = appendCommentText(element, new StringBuilder());
+ String markdown = convertToMarkdown(text.toString());
+ String indent = getElementIndent(element);
+ String[] lines = markdown.split("\n");
+ StringBuilder result = new StringBuilder(text.length() + (indent.length() + 4) * lines.length);
+ for (String line : lines) {
+ if (!result.isEmpty()) {
+ result.append(indent);
+ }
+ result.append("///").append(line).append('\n');
+ }
+
+ Document document = element.getContainingFile().getFileDocument();
+ int startOffset = element.getTextOffset();
+ int endOffset = element.getNextSibling() instanceof PsiWhiteSpace whiteSpace
+ ? whiteSpace.getTextOffset() + whiteSpace.getTextLength()
+ : startOffset + element.getTextLength();
+ document.replaceString(startOffset, endOffset, result);
+ }
+
+ private static StringBuilder appendCommentText(@NotNull PsiElement element, StringBuilder result) {
+ for (@NotNull PsiElement child : element.getChildren()) {
+ if (isDocToken(child, JavaDocTokenType.DOC_COMMENT_LEADING_ASTERISKS)) {
+ continue;
+ }
+ else if (child instanceof PsiDocToken token && SKIP_TOKENS.contains(token.getTokenType())) {
+ continue;
+ }
+ else if (child instanceof PsiInlineDocTag inlineDocTag) {
+ PsiElement nameElement = inlineDocTag.getNameElement();
+ PsiElement next = nameElement.getNextSibling();
+ if (next instanceof PsiWhiteSpace && next.getText().contains("\n")) {
+ result.append("\n ");
+ }
+ String name = inlineDocTag.getName();
+ if ("code".equals(name)) {
+ handleCodeInlineDocTag(inlineDocTag, result);
+ }
+ else if ("link".equals(name)) {
+ handleLinkInlineDocTag(inlineDocTag, result);
+ }
+ else {
+ handleGenericInlineDocTag(inlineDocTag, result);
+ }
+ continue;
+ }
+ if (child instanceof PsiDocTag || child instanceof PsiDocTagValue) {
+ appendCommentText(child, result);
+ continue;
+ }
+ else if (child instanceof PsiWhiteSpace) {
+ if (!isDocToken(child.getNextSibling(), JavaDocTokenType.DOC_COMMENT_END)) {
+ String text = child.getText();
+ if (text.contains("\n")) {
+ if (!result.isEmpty()) {
+ result.append("\n");
+ }
+ }
+ else {
+ result.append(text);
+ }
+ }
+ continue;
+ }
+ result.append(child.getText());
+ }
+ return result;
+ }
+
+ private static String convertToMarkdown(String html) {
+ int tag = -1;
+ boolean endTag = false;
+ boolean newLine = false;
+ boolean inList = false;
+ StringBuilder result = new StringBuilder();
+ for (int i = 0, length = html.length(); i < length; i++) {
+ char c = html.charAt(i);
+ if (tag >= 0) {
+ if (isLetterOrDigitAscii(c)) {
+ continue;
+ }
+ else if (c == '/') {
+ if (i == tag + 1) endTag = true;
+ continue;
+ }
+ else if (c == '>') {
+ String name = html.substring(tag + (endTag ? 2 : 1), (html.charAt(i-1) == '/') ? i - 1 : i);
+ if ("li".equals(name)) {
+ if (endTag) {
+ inList = false;
+ }
+ else {
+ if (" ".equals(result.substring(result.length() - 4))) {
+ result.delete(result.length() - 4, result.length());
+ }
+ result.append(" - ");
+ inList = true;
+ }
+ }
+ else if ("em".equals(name) || "i".equals(name)) {
+ result.append('_');
+ }
+ else if ("b".equals(name) || "strong".equals(name)) {
+ result.append("**");
+ }
+ else if ("hr".equals(name)) {
+ result.append("---");
+ }
+ else if ("p".equals(name)) {
+ if (i + 1 < length && html.charAt(i + 1) != '\n') result.append("\n ");
+ }
+ else if ("br".equals(name)) {
+ result.append(" \n");
+ }
+ else if ("ul".equals(name)) {
+ if (endTag) inList = false;
+ }
+ else {
+ result.append(html, tag, i + 1);
+ }
+ }
+ else {
+ result.append(html, tag, i + 1);
+ }
+ tag = -1;
+ endTag = false;
+ }
+ else {
+ if (c == '\n') {
+ if (newLine && !(i + 2 < length && html.charAt(i + 2) == '@')) {
+ continue;
+ }
+ result.append(inList ? "\n " : "\n");
+ newLine = true;
+ }
+ else {
+ if (newLine && inList && c == ' ') continue;
+ newLine = false;
+ if (c == '<') {
+ tag = i;
+ }
+ else {
+ result.append(c);
+ }
+ }
+ }
+ }
+ return result.toString();
+ }
+
+ private static boolean isLetterOrDigitAscii(char cur) {
+ return cur >= 'a' && cur <= 'z' || cur >= 'A' && cur <= 'Z' || cur >= '0' && cur <= '9';
+ }
+
+ private static String getElementIndent(PsiElement element) {
+ PsiElement leaf = PsiTreeUtil.prevLeaf(element);
+ if (!(leaf instanceof PsiWhiteSpace)) {
+ return "";
+ }
+ String text = leaf.getText();
+ final int lineBreak = text.lastIndexOf('\n');
+ return text.substring(lineBreak + 1);
+ }
+
+ private static void handleGenericInlineDocTag(PsiElement element, StringBuilder result) {
+ PsiElement[] children = element.getChildren();
+ if (children.length > 0) {
+ for (@NotNull PsiElement child : children) {
+ handleGenericInlineDocTag(child, result);
+ }
+ return;
+ }
+ if (element instanceof PsiWhiteSpace) {
+ String text = element.getText();
+ if (text.contains("\n")) {
+ result.append("\n ");
+ }
+ else {
+ result.append(text);
+ }
+ return;
+ }
+ else if (isDocToken(element, JavaDocTokenType.DOC_COMMENT_LEADING_ASTERISKS)) {
+ return;
+ }
+ result.append(element.getText());
+ }
+
+ private static void handleCodeInlineDocTag(PsiInlineDocTag inlineDocTag, StringBuilder result) {
+ result.append('`');
+ for (PsiElement dataElement : inlineDocTag.getDataElements()) {
+ if (dataElement instanceof PsiDocToken) {
+ result.append(dataElement.getText().trim());
+ }
+ }
+ result.append('`');
+ }
+
+ private static void handleLinkInlineDocTag(PsiInlineDocTag inlineDocTag, StringBuilder result) {
+ result.append('[');
+ PsiElement[] dataElements = inlineDocTag.getDataElements();
+ boolean dataFound = false;
+ for (PsiElement dataElement : dataElements) {
+ if (dataElement instanceof PsiDocToken) {
+ String text = dataElement.getText().trim();
+ if (!text.isEmpty()) {
+ result.append(text);
+ dataFound = true;
+ }
+ }
+ }
+ if (dataFound) result.append("][");
+ for (PsiElement dataElement : dataElements) {
+ if (dataElement instanceof PsiDocMethodOrFieldRef) {
+ for (@NotNull PsiElement refChild : dataElement.getChildren()) {
+ if (refChild instanceof PsiDocToken) {
+ result.append(refChild.getText());
+ }
+ else if (refChild instanceof PsiDocTagValue) {
+ for (@NotNull PsiElement valueChild : refChild.getChildren()) {
+ if (valueChild instanceof PsiWhiteSpace) {
+ if (valueChild.getText().contains("\n")) {
+ result.append("\n ");
+ }
+ continue;
+ }
+ if (isDocToken(valueChild, JavaDocTokenType.DOC_COMMENT_LEADING_ASTERISKS)) continue;
+ result.append(valueChild.getText());
+ }
+ }
+ }
+ }
+ else if (!(dataElement instanceof PsiDocToken) && !(dataElement instanceof PsiWhiteSpace)) {
+ result.append(dataElement.getText());
+ }
+ }
+ result.append(']');
+ }
+
+ private static boolean isDocToken(PsiElement element, IElementType tokenType) {
+ return element instanceof PsiDocToken token && tokenType == token.getTokenType();
+ }
+ }
+}
diff --git a/java/java-impl/src/META-INF/InspectionGadgets.xml b/java/java-impl/src/META-INF/InspectionGadgets.xml
index a607052da307..d30e4173acd2 100644
--- a/java/java-impl/src/META-INF/InspectionGadgets.xml
+++ b/java/java-impl/src/META-INF/InspectionGadgets.xml
@@ -1338,6 +1338,10 @@
key="while.can.be.foreach.display.name" groupBundle="messages.InspectionsBundle"
groupKey="group.names.language.level.specific.issues.and.migration.aids5" enabledByDefault="true" level="WARNING"
implementationClass="com.siyeh.ig.migration.WhileCanBeForeachInspection"/>
+
+
+Reports Javadoc comments that can be converted to Markdown documentation comments.
+Example:
+
+ /**
+ * For blubbering of the florz.
+ *
+ * Similar to {@link com.deeps.Querp querping} class.
+ */
+ class FlorzBlubber {
+ }
+
+After the quick-fix is applied:
+
+ /// For blubbering of the florz.
+ /// Similar to [querping][com.deeps.Querp] class.
+ class FlorzBlubber {
+ }
+
+
+New in 2024.2
+
+
+