This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-doxia.git
The following commit(s) were added to refs/heads/master by this push:
new f76f1b8c More Javadoc fixes
f76f1b8c is described below
commit f76f1b8c353551b8e666741df281af0e4b6239bf
Author: Konrad Windszus <[email protected]>
AuthorDate: Tue Mar 17 15:59:20 2026 +0100
More Javadoc fixes
---
.../java/org/apache/maven/doxia}/package-info.java | 53 +++++--------------
.../maven/doxia/parser/Xhtml5BaseParser.java | 4 +-
.../javadoc/org/apache/maven/doxia/package.html | 60 ----------------------
.../module/markdown/BufferingStackWriter.java | 3 +-
.../org/apache/maven/doxia/sink/package-info.java | 7 +--
5 files changed, 20 insertions(+), 107 deletions(-)
diff --git
a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/package-info.java
b/doxia-core/src/main/java/org/apache/maven/doxia/package-info.java
similarity index 53%
copy from
doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/package-info.java
copy to doxia-core/src/main/java/org/apache/maven/doxia/package-info.java
index 94e43b5a..68d292e1 100644
--- a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/package-info.java
+++ b/doxia-core/src/main/java/org/apache/maven/doxia/package-info.java
@@ -18,57 +18,28 @@
*/
/**
- * The Doxia API is based on {@link Sink} objects: each Sink consumes Doxia
events to produce a resultant output format (in most cases XHTML).
- * Consumers just create a Sink object from the {@link SinkFactory} for the
desired format and call its methods.
- *
- * Providers implement the {@link Sink} and {@link SinkFactory} interface to
write the desired output.
- * Those need to leverage JSR330 annotations to be discoverable by the Eclipse
Sisu container.
- * Consumers can then inject the desired SinkFactory using the {@code @Inject}
and {@code @Named} annotation with the name of the format (e.g. "xhtml", "fml",
"markdown", etc.).
+ * The Doxia API is based on {@link org.apache.maven.doxia.sink.Sink} and
{@link org.apache.maven.doxia.parser.Parser} objects: its goal is to parse a
given source model using a given parser, and emits Doxia events
+ * into the given sink.
+ * Further information about the Sink API in {@link
org.apache.maven.doxia.sink} and the Parser API in {@link
org.apache.maven.doxia.parser}.
+ * The {@link Doxia} interface is just a high-level API to ease using a parser.
*
* <h2>Using Maven Doxia API</h2>
* <pre>
- *
* File userDir = new File( System.getProperty ( "user.dir" ) );
+ * File inputFile = new File( userDir, "test.md" );
* File outputFile = new File( userDir, "test.html" );
*
- * {@code @Inject @Named("driver")}
- * SinkFactory sinkFactory;
+ * Reader source = ReaderFactory.newReader( inputFile, "UTF-8" );
*
+ * {@code @Inject @Named("html")}
+ * SinkFactory sinkFactory;
+ * {@code @Inject}
+ * Doxia doxia
* try (Sink sink = sinkFactory.createSink(outputFile.getParentFile(),
outputFile.getName())) {
- *
- * // Sink head
- * sink.head();
- *
- * sink.title();
- * sink.text("Title");
- * sink.title_();
- *
- * sink.author();
- * sink.text("Author");
- * sink.author_();
- *
- * sink.date();
- * sink.text("Date");
- * sink.date_();
- *
- * sink.head_();
- * // Sink head
- *
- * sink.body();
- *
- * sink.paragraph();
- * sink.text("Paragraph 1, line 1.");
- * sink.paragraph_();
- *
- * ...
- *
- * sink.body_();
+ * doxia.parse( source, "apt", sink );
* }
* </pre>
- *
- *
* @see <a
href="https://eclipse.dev/sisu/org.eclipse.sisu.inject/index.html";>Eclipse Sisu
(JSR 330 DI container)</a>
* @see <a href="https://maven.apache.org/doxia/";>Maven Doxia Website</a>
- *
*/
-package org.apache.maven.doxia.sink;
+package org.apache.maven.doxia;
diff --git
a/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml5BaseParser.java
b/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml5BaseParser.java
index f43810e5..9a4014ea 100644
---
a/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml5BaseParser.java
+++
b/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml5BaseParser.java
@@ -42,7 +42,9 @@ import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
- * Common base parser for xhtml5 events.
+ * Common base parser for XHTML5 (now <a
href="https://html.spec.whatwg.org/multipage/#toc-the-xhtml-syntax";>HTML Living
standard, XML syntax</a>) elements and attributes.
+ *
+ * @see <a
href="https://html.spec.whatwg.org/multipage/introduction.html#history-2";>HTML
Living standard, history</a>
*/
public class Xhtml5BaseParser extends AbstractXmlParser implements HtmlMarkup {
private static final Logger LOGGER =
LoggerFactory.getLogger(Xhtml5BaseParser.class);
diff --git a/doxia-core/src/main/javadoc/org/apache/maven/doxia/package.html
b/doxia-core/src/main/javadoc/org/apache/maven/doxia/package.html
deleted file mode 100644
index 6282d27a..00000000
--- a/doxia-core/src/main/javadoc/org/apache/maven/doxia/package.html
+++ /dev/null
@@ -1,60 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-<body>
- <h1>Maven Doxia API.</h1>
- <p>The Doxia API is based on <i>Sinks</i> and <i>Parser</i> objects: its
goal is to parse a given source model
- using a given parser, and emits Doxia events into the given sink.</p>
-
- <h2>Using Maven Doxia API</h2>
- <p>The following snippet shows how to use the Doxia API:</p>
-
- <div style="text-align:center" class="java">
- <table>
- <tr>
- <!-- start source code -->
- <td nowrap="nowrap" style="text-align:left">
- <code>
- <span style="color:#ffffff"> </span><span
style="color:#000000">File userDir = </span><span
style="color:#7f0055"><b>new </b></span><span
style="color:#000000">File</span><span
style="color:#000000">( </span><span
style="color:#000000">System.getProperty </span><span
style="color:#000000">( </span><span
style="color:#2a00ff">"user.dir" </span><span
style="color:#000000">) )</span><span style="color:#000000">;</sp [...]
- <span style="color:#ffffff"> </span><span
style="color:#000000">File inputFile = </span><span
style="color:#7f0055"><b>new </b></span><span
style="color:#000000">File</span><span
style="color:#000000">( </span><span
style="color:#000000">userDir, </span><span
style="color:#2a00ff">"test.apt" </span><span
style="color:#000000">)</span><span style="color:#000000">;</span><br/>
- <span style="color:#ffffff"> </span><span
style="color:#000000">File outputFile = </span><span
style="color:#7f0055"><b>new </b></span><span
style="color:#000000">File</span><span
style="color:#000000">( </span><span
style="color:#000000">userDir, </span><span
style="color:#2a00ff">"test.html" </span><span
style="color:#000000">)</span><span style="color:#000000">;</span><br/>
- <span style="color:#ffffff"></span><br />
- <span style="color:#ffffff"> </span><span
style="color:#000000">Reader source = ReaderFactory.newReader</span><span
style="color:#000000">( </span><span
style="color:#000000">inputFile, </span><span
style="color:#2a00ff">"UTF-8" </span><span
style="color:#000000">)</span><span style="color:#000000">;</span><br />
- <span style="color:#ffffff"></span><br />
- <span style="color:#ffffff"> </span><span
style="color:#000000">SinkFactory sinkFactory = </span><span
style="color:#000000">(</span><span
style="color:#000000">SinkFactory</span><span
style="color:#000000">) </span><span
style="color:#000000">lookup</span><span
style="color:#000000">( </span><span
style="color:#000000">SinkFactory.ROLE, </span><span
style="color:#2a00ff">"html" </span><span
style="color:#000000">)</span>< [...]
- <span style="color:#ffffff"> </span><span
style="color:#000000">Sink sink = sinkFactory.createSink</span><span
style="color:#000000">( </span><span
style="color:#000000">outputFile.getParentFile</span><span
style="color:#000000">()</span><span
style="color:#000000">, outputFile.getName</span><span
style="color:#000000">() ) )</span><span
style="color:#000000">;</span><br />
- <span style="color:#ffffff"></span><br />
- <span style="color:#ffffff"> </span><span
style="color:#000000">Doxia doxia = </span><span
style="color:#000000">(</span><span style="color:#000000">Doxia</span><span
style="color:#000000">) </span><span
style="color:#000000">lookup</span><span
style="color:#000000">( </span><span
style="color:#000000">Doxia.ROLE </span><span
style="color:#000000">)</span><span style="color:#000000">; </span><span
style="color:#3f7f5f">// Ple [...]
- <span style="color:#ffffff"></span><br />
- <span style="color:#ffffff"> </span><span
style="color:#000000">doxia.parse</span><span
style="color:#000000">( </span><span
style="color:#000000">source, </span><span
style="color:#2a00ff">"apt"</span><span
style="color:#000000">, sink </span><span
style="color:#000000">)</span><span style="color:#000000">;</span>
- </code>
- </td>
- <!-- end source code -->
- </tr>
- </table>
- </div>
-
- <h2>Resources</h2>
- <ul>
- <li><a href="https://maven.apache.org/doxia/";>Maven Doxia Website</a></li>
- <li><a href="https://codehaus-plexus.github.io/";>Plexus</a></li>
- </ul>
-</body>
diff --git
a/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/BufferingStackWriter.java
b/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/BufferingStackWriter.java
index b69f57da..b658e559 100644
---
a/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/BufferingStackWriter.java
+++
b/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/BufferingStackWriter.java
@@ -76,8 +76,7 @@ public class BufferingStackWriter extends Writer {
}
/**
- * Retrieves the content of the current buffer and removes it from the
stack. Returns null if the stack is empty.
- * @return the content of the current buffer, or null if the stack is empty
+ * Remove the current buffer from the stack. The content of the current
buffer is discarded. The previous buffer in the stack becomes the current
buffer.
*/
public void removeBuffer() {
bufferStack.remove();
diff --git
a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/package-info.java
b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/package-info.java
index 94e43b5a..efed1d34 100644
--- a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/package-info.java
+++ b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/package-info.java
@@ -22,10 +22,10 @@
* Consumers just create a Sink object from the {@link SinkFactory} for the
desired format and call its methods.
*
* Providers implement the {@link Sink} and {@link SinkFactory} interface to
write the desired output.
- * Those need to leverage JSR330 annotations to be discoverable by the Eclipse
Sisu container.
+ * Those need to leverage JSR 330 annotations to be discoverable by the
Eclipse Sisu container.
* Consumers can then inject the desired SinkFactory using the {@code @Inject}
and {@code @Named} annotation with the name of the format (e.g. "xhtml", "fml",
"markdown", etc.).
*
- * <h2>Using Maven Doxia API</h2>
+ * <h2>Using Maven Doxia Sink API (without a parser)</h2>
* <pre>
*
* File userDir = new File( System.getProperty ( "user.dir" ) );
@@ -65,7 +65,8 @@
* sink.body_();
* }
* </pre>
- *
+ *
+ * Alternatively one can populate a Sink through a {@link
org.apache.maven.doxia.parser.Parser} and the {@link
org.apache.maven.doxia.Doxia} interface, which is a high-level API to ease
using a parser.
*
* @see <a
href="https://eclipse.dev/sisu/org.eclipse.sisu.inject/index.html";>Eclipse Sisu
(JSR 330 DI container)</a>
* @see <a href="https://maven.apache.org/doxia/";>Maven Doxia Website</a>
