From 34ac682c137bc4dd2c2b54932ec01a2747da0140 Mon Sep 17 00:00:00 2001
From: Konrad Windszus <kwin@apache.org>
Date: Tue, 8 Oct 2024 15:11:35 +0200
Subject: [PATCH 1/3] [DOXIA-746] Sink API: add method for block comment

Add tests for consecutive comments
---
 .../maven/doxia/sink/impl/SinkWrapper.java    |  5 ++
 .../maven/doxia/sink/impl/Xhtml5BaseSink.java | 48 +++++++++-------
 .../doxia/sink/impl/AbstractSinkTest.java     | 57 +++++++++++++++++++
 .../doxia/sink/impl/SinkEventTestingSink.java |  5 ++
 .../maven/doxia/module/apt/AptParser.java     |  2 +-
 .../maven/doxia/module/apt/AptSink.java       | 10 ++--
 .../maven/doxia/module/apt/AptParserTest.java | 26 +++++++++
 .../maven/doxia/module/apt/AptSinkTest.java   | 19 ++++++-
 .../src/test/resources/test/comments2.apt     |  6 ++
 .../doxia/module/markdown/MarkdownSink.java   | 16 ++++--
 .../module/markdown/MarkdownSinkTest.java     |  9 ++-
 .../maven/doxia/module/xdoc/XdocSinkTest.java |  7 ++-
 .../doxia/module/xhtml5/Xhtml5SinkTest.java   |  7 ++-
 .../org/apache/maven/doxia/sink/Sink.java     | 11 ++++
 14 files changed, 194 insertions(+), 34 deletions(-)
 create mode 100644 doxia-modules/doxia-module-apt/src/test/resources/test/comments2.apt

diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/SinkWrapper.java b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/SinkWrapper.java
index fcf5728f7..c9e01bdc1 100644
--- a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/SinkWrapper.java
+++ b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/SinkWrapper.java
@@ -513,6 +513,11 @@ public void comment(String comment) {
         delegate.comment(comment);
     }
 
+    @Override
+    public void comment(String comment, boolean isBlockComment) {
+        delegate.comment(comment, isBlockComment);
+    }
+
     @Override
     public void unknown(String name, Object[] requiredParams, SinkEventAttributes attributes) {
         delegate.unknown(name, requiredParams, attributes);
diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java
index bbe3107e6..29387849c 100644
--- a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java
+++ b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java
@@ -1403,7 +1403,7 @@ public void lineBreakOpportunity(SinkEventAttributes attributes) {
     /** {@inheritDoc} */
     @Override
     public void pageBreak() {
-        comment(" PB ");
+        comment(" PB ", false);
     }
 
     /** {@inheritDoc} */
@@ -1444,34 +1444,44 @@ public void rawText(String text) {
         }
     }
 
-    /** {@inheritDoc} */
     @Override
     public void comment(String comment) {
+        comment(comment, false);
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public void comment(String comment, boolean isBlockComment) {
         if (comment != null) {
-            final String originalComment = comment;
+            write(encodeAsHtmlComment(comment, isBlockComment, getLocationLogPrefix()));
+        }
+    }
 
-            // http://www.w3.org/TR/2000/REC-xml-20001006#sec-comments
-            while (comment.contains("--")) {
-                comment = comment.replace("--", "- -");
-            }
+    public static String encodeAsHtmlComment(String comment, boolean isBlockComment, String locationLogPrefix) {
+        final String originalComment = comment;
 
-            if (comment.endsWith("-")) {
-                comment += " ";
-            }
+        // http://www.w3.org/TR/2000/REC-xml-20001006#sec-comments
+        while (comment.contains("--")) {
+            comment = comment.replace("--", "- -");
+        }
 
-            if (!originalComment.equals(comment)) {
-                LOGGER.warn(
-                        "{}Modified invalid comment '{}' to '{}'", getLocationLogPrefix(), originalComment, comment);
-            }
+        if (comment.endsWith("-")) {
+            comment += " ";
+        }
 
-            final StringBuilder buffer = new StringBuilder(comment.length() + 7);
+        if (!originalComment.equals(comment)) {
+            LOGGER.warn("{}Modified invalid comment '{}' to '{}'", locationLogPrefix, originalComment, comment);
+        }
 
-            buffer.append(LESS_THAN).append(BANG).append(MINUS).append(MINUS);
-            buffer.append(comment);
-            buffer.append(MINUS).append(MINUS).append(GREATER_THAN);
+        final StringBuilder buffer = new StringBuilder(comment.length() + 7);
 
-            write(buffer.toString());
+        buffer.append(LESS_THAN).append(BANG).append(MINUS).append(MINUS);
+        buffer.append(comment);
+        buffer.append(MINUS).append(MINUS).append(GREATER_THAN);
+        if (isBlockComment) {
+            buffer.append(EOL);
         }
+        return buffer.toString();
     }
 
     /**
diff --git a/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/AbstractSinkTest.java b/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/AbstractSinkTest.java
index e109bad15..5cd096d2c 100644
--- a/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/AbstractSinkTest.java
+++ b/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/AbstractSinkTest.java
@@ -1142,6 +1142,54 @@ public void testComment() {
         assertEquals(expected, actual, "Wrong comment!");
     }
 
+    /**
+     * Checks the line separator between two consecutive comments.
+     */
+    @Test
+    public void testTwoConsecutiveInlineComments() {
+        String comment = "Simple comment";
+        sink.comment(comment);
+        sink.comment(comment);
+        sink.flush();
+        sink.close();
+        assertEquals(getCommentBlock(comment) + getCommentBlock(comment), testWriter.toString(), "Wrong comment!");
+    }
+
+    /**
+     * Checks the line separator between two consecutive comments.
+     */
+    @Test
+    public void testTwoConsecutiveBlockComments() {
+        String comment = "Simple comment";
+        sink.comment(comment, true);
+        sink.comment(comment, true);
+        sink.flush();
+        sink.close();
+        assertEquals(
+                getCommentBlock(comment) + EOL + getCommentBlock(comment) + EOL,
+                testWriter.toString(),
+                "Wrong comment!");
+    }
+
+    /**
+     * Checks the line separator between comment and paragraph (in most markup languages a block element which needs to start in the new line)
+     */
+    @Test
+    public void testCommentFollowedByParagraph() {
+        String comment = "Simple comment";
+        sink.comment(comment);
+        sink.paragraph();
+        sink.text("Paragraph");
+        sink.paragraph_();
+        sink.flush();
+        sink.close();
+
+        String actual = testWriter.toString();
+        String expected = getCommentBlockFollowedByParagraph(comment, "Paragraph");
+
+        assertEquals(expected, actual, "Wrong comment!");
+    }
+
     // ----------------------------------------------------------------------
     // Utility methods
     // ----------------------------------------------------------------------
@@ -1545,6 +1593,15 @@ protected String getOutputDir() {
      */
     protected abstract String getCommentBlock(String text);
 
+    /**
+     * Returns a comment block generated by this sink followed by a paragraph block
+     * @param text The text to use.
+     * @return The result of invoking a comment block followed by a paragraph block on the current sink.
+     * @see #testCommentFollowedByParagraph()
+     * @since 2.1.0
+     */
+    protected abstract String getCommentBlockFollowedByParagraph(String comment, String paragraph);
+
     protected final void verifyValignSup(String text) {
         sink.text("ValignSup", new SinkEventAttributeSet(SinkEventAttributes.VALIGN, "sup"));
         sink.flush();
diff --git a/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/SinkEventTestingSink.java b/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/SinkEventTestingSink.java
index 528568ed8..554eeb747 100644
--- a/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/SinkEventTestingSink.java
+++ b/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/SinkEventTestingSink.java
@@ -287,6 +287,11 @@ public void rawText(String text) {
         addEvent("rawText", new Object[] {text});
     }
 
+    @Override
+    public void comment(String comment, boolean isBlockComment) {
+        addEvent("comment", new Object[] {comment, isBlockComment});
+    }
+
     @Override
     public void comment(String comment) {
         addEvent("comment", new Object[] {comment});
diff --git a/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptParser.java b/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptParser.java
index 52e8ec5a0..2d9c8eb88 100644
--- a/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptParser.java
+++ b/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptParser.java
@@ -1855,7 +1855,7 @@ private class Comment extends Block {
         /** {@inheritDoc} */
         public void traverse() throws AptParseException {
             if (isEmitComments()) {
-                AptParser.this.sink.comment(text);
+                AptParser.this.sink.comment(text, true);
             }
         }
     }
diff --git a/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java b/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java
index 656f1efc6..8df6368bf 100644
--- a/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java
+++ b/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java
@@ -209,9 +209,6 @@ public void head(SinkEventAttributes attributes) {
     public void head_() {
         headerFlag = false;
 
-        if (!startFlag) {
-            write(EOL);
-        }
         write(HEADER_START_MARKUP + EOL);
         if (title != null) {
             write(" " + title + EOL);
@@ -839,7 +836,12 @@ public void rawText(String text) {
 
     /** {@inheritDoc} */
     public void comment(String comment) {
-        rawText((startFlag ? "" : EOL) + COMMENT + COMMENT + comment);
+        comment(comment, false);
+    }
+
+    @Override
+    public void comment(String comment, boolean isBlockComment) {
+        rawText("" + COMMENT + COMMENT + comment + EOL); // comments are always block comments in APT
     }
 
     /**
diff --git a/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptParserTest.java b/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptParserTest.java
index c6a6a501c..f79d61ccb 100644
--- a/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptParserTest.java
+++ b/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptParserTest.java
@@ -85,6 +85,32 @@ public void testCommentsBeforeTitle() throws Exception {
                         + " -----" + EOL + " Test DOXIA-379"));
     }
 
+    @Test
+    public void testCommentsAfterParagraph() throws Exception {
+        SinkEventTestingSink sink = new SinkEventTestingSink();
+        try (Reader reader = getTestReader("test/comments2")) {
+            createParser().parse(reader, sink);
+        }
+
+        Iterator<SinkEventElement> it = sink.getEventList().iterator();
+
+        assertSinkStartsWith(
+                it,
+                "head",
+                "head_",
+                "body",
+                "section1",
+                "sectionTitle1",
+                "text",
+                "sectionTitle1_",
+                "paragraph",
+                "text",
+                "paragraph_");
+        assertSinkEquals(it.next(), "comment", "some comment", Boolean.TRUE);
+        assertSinkEquals(it.next(), "comment", "another comment", Boolean.TRUE);
+        assertSinkEquals(it, "paragraph", "text", "paragraph_", "section1_", "body_");
+    }
+
     @Test
     public void testSnippet() throws Exception {
         // DOXIA-259
diff --git a/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptSinkTest.java b/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptSinkTest.java
index 3e23c073e..f27e23d81 100644
--- a/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptSinkTest.java
+++ b/doxia-modules/doxia-module-apt/src/test/java/org/apache/maven/doxia/module/apt/AptSinkTest.java
@@ -355,7 +355,24 @@ private static String getSpecialCharacters(char c) {
 
     /** {@inheritDoc} */
     protected String getCommentBlock(String text) {
-        return "~~" + text;
+        return "~~" + text + EOL;
+    }
+
+    @Override
+    protected String getCommentBlockFollowedByParagraph(String comment, String paragraph) {
+        return getCommentBlock(comment) + getParagraphBlock(paragraph);
+    }
+
+    /* Overwrite the test from AbstractSinkTest as EOLs are part of getCommentBlock(...) */
+    @Test
+    public void testTwoConsecutiveBlockComments() {
+        final Sink sink = getSink();
+        String comment = "Simple comment";
+        sink.comment(comment, true);
+        sink.comment(comment, true);
+        sink.flush();
+        sink.close();
+        assertEquals(getCommentBlock(comment) + getCommentBlock(comment), getSinkContent(), "Wrong comment!");
     }
 
     /**
diff --git a/doxia-modules/doxia-module-apt/src/test/resources/test/comments2.apt b/doxia-modules/doxia-module-apt/src/test/resources/test/comments2.apt
new file mode 100644
index 000000000..5f4434bb7
--- /dev/null
+++ b/doxia-modules/doxia-module-apt/src/test/resources/test/comments2.apt
@@ -0,0 +1,6 @@
+Section Title
+
+  paragraph
+~~some comment
+~~another comment
+  text
diff --git a/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownSink.java b/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownSink.java
index 91dceae90..7fdcd5f74 100644
--- a/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownSink.java
+++ b/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownSink.java
@@ -35,6 +35,7 @@
 import org.apache.maven.doxia.sink.SinkEventAttributes;
 import org.apache.maven.doxia.sink.impl.AbstractTextSink;
 import org.apache.maven.doxia.sink.impl.SinkEventAttributeSet;
+import org.apache.maven.doxia.sink.impl.Xhtml5BaseSink;
 import org.apache.maven.doxia.util.HtmlTools;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -93,13 +94,13 @@ public class MarkdownSink extends AbstractTextSink implements MarkdownMarkup {
 
     private String figureSrc;
 
-    /** Most important contextual metadata (of the surrounding element) */
+    /** Most important contextual metadata (of elements). This contains information about necessary escaping rules, potential prefixes and newlines */
     enum ElementContext {
         HEAD("head", Type.GENERIC_CONTAINER, null, true),
         BODY("body", Type.GENERIC_CONTAINER, MarkdownSink::escapeMarkdown),
         // only the elements, which affect rendering of children and are different from BODY or HEAD are listed here
         FIGURE("", Type.INLINE, MarkdownSink::escapeMarkdown, true),
-        CODE_BLOCK("code block", Type.LEAF_BLOCK, null, false),
+        CODE_BLOCK("code block", Type.LEAF_BLOCK, null),
         CODE_SPAN("code span", Type.INLINE, null),
         TABLE_CAPTION("table caption", Type.INLINE, MarkdownSink::escapeMarkdown),
         TABLE_CELL(
@@ -269,8 +270,8 @@ private void ensureBeginningOfLine() {
     }
 
     /**
-     * Ensures that the {@link #writer} is either at the beginning or preceded by a blank line.
-     * Optionally writes a blank line to ensure that.
+     * Ensures that the {@link #writer} is preceded by a blank line.
+     * Optionally writes a blank line or just line delimiter to ensure that.
      */
     private void ensureBlankLine() {
         // prevent duplicate blank lines
@@ -882,7 +883,12 @@ public void rawText(String text) {
 
     @Override
     public void comment(String comment) {
-        rawText(COMMENT_START + comment + COMMENT_END);
+        comment(comment, false);
+    }
+
+    @Override
+    public void comment(String comment, boolean isBlockComment) {
+        rawText(Xhtml5BaseSink.encodeAsHtmlComment(comment, isBlockComment, getLocationLogPrefix()));
     }
 
     /**
diff --git a/doxia-modules/doxia-module-markdown/src/test/java/org/apache/maven/doxia/module/markdown/MarkdownSinkTest.java b/doxia-modules/doxia-module-markdown/src/test/java/org/apache/maven/doxia/module/markdown/MarkdownSinkTest.java
index 44d1162e4..beb386d4f 100644
--- a/doxia-modules/doxia-module-markdown/src/test/java/org/apache/maven/doxia/module/markdown/MarkdownSinkTest.java
+++ b/doxia-modules/doxia-module-markdown/src/test/java/org/apache/maven/doxia/module/markdown/MarkdownSinkTest.java
@@ -332,9 +332,14 @@ private String getEscapedText(String text) {
         return text.replaceAll("\\\\|\\`|\\*|_|\\{|\\}|\\[|\\]|\\(|\\)|#|\\+|\\-|\\.|\\!", "\\\\$0");
     }
 
-    /** {@inheritDoc} */
+    @Override
     protected String getCommentBlock(String text) {
-        return "<!-- " + text + " -->";
+        return "<!--" + toXmlComment(text) + "-->";
+    }
+
+    @Override
+    protected String getCommentBlockFollowedByParagraph(String comment, String paragraph) {
+        return getCommentBlock(comment) + EOL + EOL + getParagraphBlock(paragraph); // paragraph separated by blank line
     }
 
     @Test
diff --git a/doxia-modules/doxia-module-xdoc/src/test/java/org/apache/maven/doxia/module/xdoc/XdocSinkTest.java b/doxia-modules/doxia-module-xdoc/src/test/java/org/apache/maven/doxia/module/xdoc/XdocSinkTest.java
index de16c6afe..3f0315c44 100644
--- a/doxia-modules/doxia-module-xdoc/src/test/java/org/apache/maven/doxia/module/xdoc/XdocSinkTest.java
+++ b/doxia-modules/doxia-module-xdoc/src/test/java/org/apache/maven/doxia/module/xdoc/XdocSinkTest.java
@@ -373,8 +373,13 @@ public void testLinkWithTarget() {
         assertEquals("<a href=\"name\"></a><a target=\"nirvana\" href=\"name\"></a>", writer.toString());
     }
 
-    /** {@inheritDoc} */
+    @Override
     protected String getCommentBlock(String text) {
         return "<!--" + toXmlComment(text) + "-->";
     }
+
+    @Override
+    protected String getCommentBlockFollowedByParagraph(String comment, String paragraph) {
+        return getCommentBlock(comment) + getParagraphBlock(paragraph); // no line break in between
+    }
 }
diff --git a/doxia-modules/doxia-module-xhtml5/src/test/java/org/apache/maven/doxia/module/xhtml5/Xhtml5SinkTest.java b/doxia-modules/doxia-module-xhtml5/src/test/java/org/apache/maven/doxia/module/xhtml5/Xhtml5SinkTest.java
index 875c246a1..c125ee116 100644
--- a/doxia-modules/doxia-module-xhtml5/src/test/java/org/apache/maven/doxia/module/xhtml5/Xhtml5SinkTest.java
+++ b/doxia-modules/doxia-module-xhtml5/src/test/java/org/apache/maven/doxia/module/xhtml5/Xhtml5SinkTest.java
@@ -404,8 +404,13 @@ public void testHead() {
         assertTrue(actual.contains(expected), actual);
     }
 
-    /** {@inheritDoc} */
+    @Override
     protected String getCommentBlock(String text) {
         return "<!--" + toXmlComment(text) + "-->";
     }
+
+    @Override
+    protected String getCommentBlockFollowedByParagraph(String comment, String paragraph) {
+        return getCommentBlock(comment) + getParagraphBlock(paragraph); // no line break in between
+    }
 }
diff --git a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
index ec4d28331..c33c346a6 100644
--- a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
+++ b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
@@ -1724,6 +1724,17 @@ public interface Sink extends AutoCloseable {
      */
     void comment(String comment);
 
+    /**
+     * Add a comment. The default implementation will just call {@link #comment(String)}.
+     *
+     * @param comment The comment to write.
+     * @param isBlockComment If <code>true</code> this is a block comment, i.e. nothing should follow on the same line
+     * @since 2.1
+     */
+    default void comment(String comment, boolean isBlockComment) {
+        comment(comment);
+    }
+
     /**
      * Add an unknown event. This may be used by parsers to notify a general Sink about
      * an event that doesn't fit into any event defined by the Sink API.

From 5b5afb606008a81bbd9726703b93baf4c6c938fe Mon Sep 17 00:00:00 2001
From: Konrad Windszus <kwin@apache.org>
Date: Tue, 15 Oct 2024 17:47:48 +0200
Subject: [PATCH 2/3] rename argument for Sink.comment(String, boolean)

---
 .../org/apache/maven/doxia/sink/impl/SinkWrapper.java     | 4 ++--
 .../org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java  | 8 ++++----
 .../maven/doxia/sink/impl/SinkEventTestingSink.java       | 4 ++--
 .../java/org/apache/maven/doxia/module/apt/AptSink.java   | 4 ++--
 .../apache/maven/doxia/module/markdown/MarkdownSink.java  | 4 ++--
 .../src/main/java/org/apache/maven/doxia/sink/Sink.java   | 6 ++++--
 6 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/SinkWrapper.java b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/SinkWrapper.java
index c9e01bdc1..b8c9fff75 100644
--- a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/SinkWrapper.java
+++ b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/SinkWrapper.java
@@ -514,8 +514,8 @@ public void comment(String comment) {
     }
 
     @Override
-    public void comment(String comment, boolean isBlockComment) {
-        delegate.comment(comment, isBlockComment);
+    public void comment(String comment, boolean endsWithLineBreak) {
+        delegate.comment(comment, endsWithLineBreak);
     }
 
     @Override
diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java
index 29387849c..a70ec22d6 100644
--- a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java
+++ b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java
@@ -1451,13 +1451,13 @@ public void comment(String comment) {
 
     /** {@inheritDoc} */
     @Override
-    public void comment(String comment, boolean isBlockComment) {
+    public void comment(String comment, boolean endsWithLineBreak) {
         if (comment != null) {
-            write(encodeAsHtmlComment(comment, isBlockComment, getLocationLogPrefix()));
+            write(encodeAsHtmlComment(comment, endsWithLineBreak, getLocationLogPrefix()));
         }
     }
 
-    public static String encodeAsHtmlComment(String comment, boolean isBlockComment, String locationLogPrefix) {
+    public static String encodeAsHtmlComment(String comment, boolean endsWithLineBreak, String locationLogPrefix) {
         final String originalComment = comment;
 
         // http://www.w3.org/TR/2000/REC-xml-20001006#sec-comments
@@ -1478,7 +1478,7 @@ public static String encodeAsHtmlComment(String comment, boolean isBlockComment,
         buffer.append(LESS_THAN).append(BANG).append(MINUS).append(MINUS);
         buffer.append(comment);
         buffer.append(MINUS).append(MINUS).append(GREATER_THAN);
-        if (isBlockComment) {
+        if (endsWithLineBreak) {
             buffer.append(EOL);
         }
         return buffer.toString();
diff --git a/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/SinkEventTestingSink.java b/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/SinkEventTestingSink.java
index 554eeb747..17bd48847 100644
--- a/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/SinkEventTestingSink.java
+++ b/doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/SinkEventTestingSink.java
@@ -288,8 +288,8 @@ public void rawText(String text) {
     }
 
     @Override
-    public void comment(String comment, boolean isBlockComment) {
-        addEvent("comment", new Object[] {comment, isBlockComment});
+    public void comment(String comment, boolean endsWithLineBreak) {
+        addEvent("comment", new Object[] {comment, endsWithLineBreak});
     }
 
     @Override
diff --git a/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java b/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java
index 8df6368bf..87a248f3e 100644
--- a/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java
+++ b/doxia-modules/doxia-module-apt/src/main/java/org/apache/maven/doxia/module/apt/AptSink.java
@@ -840,8 +840,8 @@ public void comment(String comment) {
     }
 
     @Override
-    public void comment(String comment, boolean isBlockComment) {
-        rawText("" + COMMENT + COMMENT + comment + EOL); // comments are always block comments in APT
+    public void comment(String comment, boolean endsWithLineBreak) {
+        rawText("" + COMMENT + COMMENT + comment + EOL); // comments always end with a line break in APT
     }
 
     /**
diff --git a/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownSink.java b/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownSink.java
index 7fdcd5f74..a7a00d9ec 100644
--- a/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownSink.java
+++ b/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownSink.java
@@ -887,8 +887,8 @@ public void comment(String comment) {
     }
 
     @Override
-    public void comment(String comment, boolean isBlockComment) {
-        rawText(Xhtml5BaseSink.encodeAsHtmlComment(comment, isBlockComment, getLocationLogPrefix()));
+    public void comment(String comment, boolean endsWithLineBreak) {
+        rawText(Xhtml5BaseSink.encodeAsHtmlComment(comment, endsWithLineBreak, getLocationLogPrefix()));
     }
 
     /**
diff --git a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
index c33c346a6..63e09eb4f 100644
--- a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
+++ b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
@@ -1718,9 +1718,11 @@ public interface Sink extends AutoCloseable {
 
     /**
      * Add a comment.
+     * Semantically the same as {@link #comment(String, boolean)} with second argument being {@code false}.
      *
      * @param comment The comment to write.
      * @since 1.1
+     * @see #comment(String, boolean)
      */
     void comment(String comment);
 
@@ -1728,10 +1730,10 @@ public interface Sink extends AutoCloseable {
      * Add a comment. The default implementation will just call {@link #comment(String)}.
      *
      * @param comment The comment to write.
-     * @param isBlockComment If <code>true</code> this is a block comment, i.e. nothing should follow on the same line
+     * @param endsWithLineBreak If {@code true} comment ends with a line break, i.e. nothing else should follow on the same line
      * @since 2.1
      */
-    default void comment(String comment, boolean isBlockComment) {
+    default void comment(String comment, boolean endsWithLineBreak) {
         comment(comment);
     }
 

From 69628ed705110cfbff2586e6a644bd99001f9ba1 Mon Sep 17 00:00:00 2001
From: Konrad Windszus <kwin@apache.org>
Date: Sun, 20 Oct 2024 17:05:42 +0200
Subject: [PATCH 3/3] Use version 2.1.0-SNAPSHOT

---
 doxia-core/pom.xml                                            | 2 +-
 .../java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java | 2 +-
 doxia-modules/doxia-module-apt/pom.xml                        | 2 +-
 doxia-modules/doxia-module-fml/pom.xml                        | 2 +-
 doxia-modules/doxia-module-markdown/pom.xml                   | 2 +-
 doxia-modules/doxia-module-xdoc/pom.xml                       | 2 +-
 doxia-modules/doxia-module-xhtml5/pom.xml                     | 2 +-
 doxia-modules/pom.xml                                         | 2 +-
 doxia-sink-api/pom.xml                                        | 2 +-
 .../src/main/java/org/apache/maven/doxia/sink/Sink.java       | 2 +-
 doxia-test-docs/pom.xml                                       | 2 +-
 pom.xml                                                       | 4 ++--
 12 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/doxia-core/pom.xml b/doxia-core/pom.xml
index b944cfb2f..2ad545bb4 100644
--- a/doxia-core/pom.xml
+++ b/doxia-core/pom.xml
@@ -23,7 +23,7 @@ under the License.
   <parent>
     <groupId>org.apache.maven.doxia</groupId>
     <artifactId>doxia</artifactId>
-    <version>2.0.1-SNAPSHOT</version>
+    <version>2.1.0-SNAPSHOT</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java
index a70ec22d6..f32aba42f 100644
--- a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java
+++ b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/Xhtml5BaseSink.java
@@ -1403,7 +1403,7 @@ public void lineBreakOpportunity(SinkEventAttributes attributes) {
     /** {@inheritDoc} */
     @Override
     public void pageBreak() {
-        comment(" PB ", false);
+        comment(" PB ");
     }
 
     /** {@inheritDoc} */
diff --git a/doxia-modules/doxia-module-apt/pom.xml b/doxia-modules/doxia-module-apt/pom.xml
index 7d0be7f08..2e76006e2 100644
--- a/doxia-modules/doxia-module-apt/pom.xml
+++ b/doxia-modules/doxia-module-apt/pom.xml
@@ -23,7 +23,7 @@ under the License.
   <parent>
     <groupId>org.apache.maven.doxia</groupId>
     <artifactId>doxia-modules</artifactId>
-    <version>2.0.1-SNAPSHOT</version>
+    <version>2.1.0-SNAPSHOT</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
diff --git a/doxia-modules/doxia-module-fml/pom.xml b/doxia-modules/doxia-module-fml/pom.xml
index ea6228bf4..31e62efbe 100644
--- a/doxia-modules/doxia-module-fml/pom.xml
+++ b/doxia-modules/doxia-module-fml/pom.xml
@@ -23,7 +23,7 @@ under the License.
   <parent>
     <groupId>org.apache.maven.doxia</groupId>
     <artifactId>doxia-modules</artifactId>
-    <version>2.0.1-SNAPSHOT</version>
+    <version>2.1.0-SNAPSHOT</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
diff --git a/doxia-modules/doxia-module-markdown/pom.xml b/doxia-modules/doxia-module-markdown/pom.xml
index 24203181d..6799e15c2 100644
--- a/doxia-modules/doxia-module-markdown/pom.xml
+++ b/doxia-modules/doxia-module-markdown/pom.xml
@@ -23,7 +23,7 @@ under the License.
   <parent>
     <groupId>org.apache.maven.doxia</groupId>
     <artifactId>doxia-modules</artifactId>
-    <version>2.0.1-SNAPSHOT</version>
+    <version>2.1.0-SNAPSHOT</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
diff --git a/doxia-modules/doxia-module-xdoc/pom.xml b/doxia-modules/doxia-module-xdoc/pom.xml
index 345b83cf4..59e16d972 100644
--- a/doxia-modules/doxia-module-xdoc/pom.xml
+++ b/doxia-modules/doxia-module-xdoc/pom.xml
@@ -23,7 +23,7 @@ under the License.
   <parent>
     <groupId>org.apache.maven.doxia</groupId>
     <artifactId>doxia-modules</artifactId>
-    <version>2.0.1-SNAPSHOT</version>
+    <version>2.1.0-SNAPSHOT</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
diff --git a/doxia-modules/doxia-module-xhtml5/pom.xml b/doxia-modules/doxia-module-xhtml5/pom.xml
index a60d6d19e..3fe719063 100644
--- a/doxia-modules/doxia-module-xhtml5/pom.xml
+++ b/doxia-modules/doxia-module-xhtml5/pom.xml
@@ -23,7 +23,7 @@ under the License.
   <parent>
     <groupId>org.apache.maven.doxia</groupId>
     <artifactId>doxia-modules</artifactId>
-    <version>2.0.1-SNAPSHOT</version>
+    <version>2.1.0-SNAPSHOT</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
diff --git a/doxia-modules/pom.xml b/doxia-modules/pom.xml
index a1e118e79..83bed694a 100644
--- a/doxia-modules/pom.xml
+++ b/doxia-modules/pom.xml
@@ -23,7 +23,7 @@ under the License.
   <parent>
     <groupId>org.apache.maven.doxia</groupId>
     <artifactId>doxia</artifactId>
-    <version>2.0.1-SNAPSHOT</version>
+    <version>2.1.0-SNAPSHOT</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
diff --git a/doxia-sink-api/pom.xml b/doxia-sink-api/pom.xml
index 577beb29f..82265c113 100644
--- a/doxia-sink-api/pom.xml
+++ b/doxia-sink-api/pom.xml
@@ -23,7 +23,7 @@ under the License.
   <parent>
     <groupId>org.apache.maven.doxia</groupId>
     <artifactId>doxia</artifactId>
-    <version>2.0.1-SNAPSHOT</version>
+    <version>2.1.0-SNAPSHOT</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
diff --git a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
index 63e09eb4f..4e86588d7 100644
--- a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
+++ b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/Sink.java
@@ -1731,7 +1731,7 @@ public interface Sink extends AutoCloseable {
      *
      * @param comment The comment to write.
      * @param endsWithLineBreak If {@code true} comment ends with a line break, i.e. nothing else should follow on the same line
-     * @since 2.1
+     * @since 2.1.0
      */
     default void comment(String comment, boolean endsWithLineBreak) {
         comment(comment);
diff --git a/doxia-test-docs/pom.xml b/doxia-test-docs/pom.xml
index 3843cf1a5..168389c8b 100644
--- a/doxia-test-docs/pom.xml
+++ b/doxia-test-docs/pom.xml
@@ -23,7 +23,7 @@ under the License.
   <parent>
     <groupId>org.apache.maven.doxia</groupId>
     <artifactId>doxia</artifactId>
-    <version>2.0.1-SNAPSHOT</version>
+    <version>2.1.0-SNAPSHOT</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
 
diff --git a/pom.xml b/pom.xml
index 73efb2786..c7ae47c6b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -29,7 +29,7 @@ under the License.
 
   <groupId>org.apache.maven.doxia</groupId>
   <artifactId>doxia</artifactId>
-  <version>2.0.1-SNAPSHOT</version>
+  <version>2.1.0-SNAPSHOT</version>
   <packaging>pom</packaging>
 
   <name>Doxia</name>
@@ -84,7 +84,7 @@ under the License.
     <javaVersion>8</javaVersion>
     <maven.site.path>doxia-archives/doxia-LATEST</maven.site.path>
     <checkstyle.violation.ignore>RedundantThrows,NewlineAtEndOfFile,ParameterNumber,MethodLength,FileLength,MethodName,InnerAssignment,MagicNumber</checkstyle.violation.ignore>
-    <project.build.outputTimestamp>2024-09-28T17:58:29Z</project.build.outputTimestamp>
+    <project.build.outputTimestamp>2024-10-20T15:01:56Z</project.build.outputTimestamp>
     <slf4jVersion>1.7.36</slf4jVersion>
     <xmlunitVersion>2.10.0</xmlunitVersion>
   </properties>