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 8643a46d Clean up javadoc
8643a46d is described below
commit 8643a46d30273c7f2f5d4c3dc012a5a78b172354
Author: Konrad Windszus <[email protected]>
AuthorDate: Tue Mar 17 14:54:39 2026 +0100
Clean up javadoc
Inline package javadoc
---
.../org/apache/maven/doxia/sink/EmptyLocator.java | 4 +
.../java/org/apache/maven/doxia/sink/Sink.java | 36 +++---
.../org/apache/maven/doxia/sink/package-info.java | 74 ++++++++++++
.../org/apache/maven/doxia/sink/package.html | 133 ---------------------
4 files changed, 96 insertions(+), 151 deletions(-)
diff --git
a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/EmptyLocator.java
b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/EmptyLocator.java
index e3633e5d..cf13c85c 100644
--- a/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/EmptyLocator.java
+++ b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/EmptyLocator.java
@@ -18,6 +18,10 @@
*/
package org.apache.maven.doxia.sink;
+/**
+ * A {@link Locator} implementation that does not provide any information.
+ * @since 2.0
+ */
public final class EmptyLocator implements Locator {
public static final Locator INSTANCE = new EmptyLocator();
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 4797345b..c8dac9f4 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
@@ -20,7 +20,7 @@ package org.apache.maven.doxia.sink;
/**
* A <i>Sink</i> consumes Doxia events to produce a resultant output format
- * (eg Docbook, PDF, XHTML...).
+ * (in most cases XHTML).
* <p>
* Doxia allows you to transform any supported input document format (ie for
which a Parser exists)
* into any supported output document format (ie for which a Sink exists).
@@ -39,12 +39,12 @@ package org.apache.maven.doxia.sink;
* Word document. The Sink is fully responsible for the final output.
* </p>
* <p>
- * You can easily integrate any custom (XML, Wiki,...) format by creating a
Doxia Parser which
+ * You can easily integrate any custom markup format by creating a Doxia
Parser which
* reads your input document and produces a proper sequence of Doxia events.
* Those can then be fed into an arbitrary Sink to produce any desired final
output.
* </p>
* <p>
- * <b>Note</b>: All implemented sink <b>should</b> use UTF-8 as encoding.
+ * <b>Note</b>: All implemented Sinks <b>should</b> use UTF-8 as encoding.
* </p>
*
* @since 1.0-alpha-6
@@ -754,9 +754,9 @@ public interface Sink extends AutoCloseable {
* </p>
* Nested lists must have the following Sink method sequence:
* <ol>
- * <li>{@link #listItem(int,SinkEventAttributes)} or {@link
#listItem(int)}</li>
- * <li>{@link #list(int,SinkEventAttributes)} or {@link #list(int)}</li>
- * <li>{@link #listItem(int,SinkEventAttributes)} or {@link
#listItem(int)}</li>
+ * <li>{@link #listItem(SinkEventAttributes)} or {@link #listItem()}</li>
+ * <li>{@link #list(SinkEventAttributes)} or {@link #list()}</li>
+ * <li>{@link #listItem(SinkEventAttributes)} or {@link #listItem()}</li>
* <li>{@code ...}</li>
* <li>{@link #listItem_()}</li>
* <li>{@link #list_()}</li>
@@ -819,9 +819,9 @@ public interface Sink extends AutoCloseable {
* </p>
* Nested lists must have the following Sink method sequence:
* <ol>
- * <li>{@link #numberedListItem(int,SinkEventAttributes)} or {@link
#numberedListItem(int)}</li>
+ * <li>{@link #numberedListItem(SinkEventAttributes)} or {@link
#numberedListItem()}</li>
* <li>{@link #numberedList(int,SinkEventAttributes)} or {@link
#numberedList(int)}</li>
- * <li>{@link #numberedListItem(int,SinkEventAttributes)} or {@link
#numberedListItem(int)}</li>
+ * <li>{@link #numberedListItem(SinkEventAttributes)} or {@link
#numberedListItem()}</li>
* <li>{@code ...}</li>
* <li>{@link #numberedListItem_()}</li>
* <li>{@link #numberedList_()}</li>
@@ -1453,7 +1453,7 @@ public interface Sink extends AutoCloseable {
void verbatim_();
/**
- * Adding a separator of sections from a text to each other. Shortcut for
{@link #horizontalRule(SinkEventAttributes)} with argument being {@code null}.
+ * Adds a separator of sections from a text to each other. Shortcut for
{@link #horizontalRule(SinkEventAttributes)} with argument being {@code null}.
*
* @see #horizontalRule(SinkEventAttributes)
*/
@@ -1476,7 +1476,7 @@ public interface Sink extends AutoCloseable {
void horizontalRule(SinkEventAttributes attributes);
/**
- * Adding a new page separator.
+ * Adds a new page separator.
*/
void pageBreak();
@@ -1695,12 +1695,12 @@ public interface Sink extends AutoCloseable {
void lineBreakOpportunity(SinkEventAttributes attributes);
/**
- * Adding a non breaking space, <i>ie</i> a space without any special
formatting operations.
+ * Adds a non breaking space, <i>ie</i> a space without any special
formatting operations.
*/
void nonBreakingSpace();
/**
- * Adding a text. Shortcut for {@link #text(String, SinkEventAttributes)}
with first argument being {@code text} and second argument being {@code null}.
+ * Adds a text. Shortcut for {@link #text(String, SinkEventAttributes)}
with first argument being {@code text} and second argument being {@code null}.
*
* @param text The text to write.
* @see #text(String,SinkEventAttributes)
@@ -1746,14 +1746,14 @@ public interface Sink extends AutoCloseable {
void text(String text, SinkEventAttributes attributes);
/**
- * Adding a raw text, <i>ie</i> a text without any special formatting
operations.
+ * Adds a raw text, <i>ie</i> a text without any special formatting
operations.
*
* @param text The text to write.
*/
void rawText(String text);
/**
- * Add a comment.
+ * Adds a comment (a text that should not be rendered but may be visible
in the source of the output document).
*
* @param comment The comment to write.
* @since 1.1
@@ -1761,7 +1761,7 @@ public interface Sink extends AutoCloseable {
void comment(String comment);
/**
- * Add a single line break with the specified indentation level. The
default implementation does nothing.
+ * Adds a single line break with the specified indentation level. The
default implementation does nothing.
* This is different from emitting a line break with {@link
#lineBreak(SinkEventAttributes)} or {@link #text(String, SinkEventAttributes)}
as those line breaks are part of the content (i.e. affect rendering)
* while this line break is purely for pretty-printing the Sink's output
and should not affect the rendering of the content.
* This is useful for Sinks that emit text-based markup languages (e.g.
HTML, XML, etc.) to produce more human-readable output.
@@ -1772,7 +1772,7 @@ public interface Sink extends AutoCloseable {
default void markupLineBreak(int indentLevel) {}
/**
- * Add an unknown event. This may be used by parsers to notify a general
Sink about
+ * Adds 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.
* Depending on the parameters, a Sink may decide whether or not to
process the event,
* emit it as raw text, as a comment, log it, etc.
@@ -1786,13 +1786,13 @@ public interface Sink extends AutoCloseable {
void unknown(String name, Object[] requiredParams, SinkEventAttributes
attributes);
/**
- * Flush the writer or the stream, if needed.
+ * Flushes the writer or the stream, if needed.
* Flushing a previously-flushed Sink has no effect.
*/
void flush();
/**
- * Close the writer or the stream, if needed.
+ * Closes the writer or the stream, if needed.
* Closing a previously-closed Sink has no effect.
*/
void close();
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
new file mode 100644
index 00000000..94e43b5a
--- /dev/null
+++ b/doxia-sink-api/src/main/java/org/apache/maven/doxia/sink/package-info.java
@@ -0,0 +1,74 @@
+/*
+ * 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.
+ */
+
+/**
+ * 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.).
+ *
+ * <h2>Using Maven Doxia API</h2>
+ * <pre>
+ *
+ * File userDir = new File( System.getProperty ( "user.dir" ) );
+ * File outputFile = new File( userDir, "test.html" );
+ *
+ * {@code @Inject @Named("driver")}
+ * SinkFactory sinkFactory;
+ *
+ * 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_();
+ * }
+ * </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;
diff --git
a/doxia-sink-api/src/main/javadoc/org/apache/maven/doxia/sink/package.html
b/doxia-sink-api/src/main/javadoc/org/apache/maven/doxia/sink/package.html
deleted file mode 100644
index 2cf5de5a..00000000
--- a/doxia-sink-api/src/main/javadoc/org/apache/maven/doxia/sink/package.html
+++ /dev/null
@@ -1,133 +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> objects: each sink consumes Doxia
events to produce a resultant output
- format (eg Docbook, PDF, XHTML...).</p>
-
-<h2>Using Maven Doxia API</h2>
-<p>The following snippet shows how to use a Doxia <code>Sink</code>:</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">;</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">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:#000000">; </span><span
-
style="color:#3f7f5f">// Plexus lookup</span><br/>
- <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:#3f7f5f">// Sink head</span><br/>
- <span style="color:#ffffff"> </span><span
style="color:#000000">sink.head</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">sink.title</span><span
- style="color:#000000">()</span><span
style="color:#000000">;</span><br/>
- <span style="color:#ffffff"> </span><span
style="color:#000000">sink.text</span><span
- style="color:#000000">( </span><span
- style="color:#2a00ff">"Title" </span><span
- style="color:#000000">)</span><span
style="color:#000000">;</span><br/>
- <span style="color:#ffffff"> </span><span
style="color:#000000">sink.title_</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">sink.author</span><span
- style="color:#000000">()</span><span
style="color:#000000">;</span><br/>
- <span style="color:#ffffff"> </span><span
style="color:#000000">sink.text</span><span
- style="color:#000000">( </span><span
-
style="color:#2a00ff">"Author" </span><span
- style="color:#000000">)</span><span
style="color:#000000">;</span><br/>
- <span style="color:#ffffff"> </span><span
style="color:#000000">sink.author_</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">sink.date</span><span
- style="color:#000000">()</span><span
style="color:#000000">;</span><br/>
- <span style="color:#ffffff"> </span><span
style="color:#000000">sink.text</span><span
- style="color:#000000">( </span><span
style="color:#2a00ff">"Date" </span><span
- style="color:#000000">)</span><span
style="color:#000000">;</span><br/>
- <span style="color:#ffffff"> </span><span
style="color:#000000">sink.date_</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">sink.head_</span><span
- style="color:#000000">()</span><span
style="color:#000000">;</span><br/>
- <span style="color:#ffffff"> </span><span
-
style="color:#3f7f5f">// Sink head</span><br/>
- <span style="color:#ffffff"></span><br/>
- <span style="color:#ffffff"> </span><span
style="color:#000000">sink.body</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">sink.paragraph</span><span
- style="color:#000000">()</span><span
style="color:#000000">;</span><br/>
- <span style="color:#ffffff"> </span><span
- style="color:#000000">sink.text</span><span
- style="color:#000000">( </span><span
style="color:#2a00ff">"Paragraph 1, line 1. Paragraph 1, line 2." </span><span
- style="color:#000000">)</span><span
style="color:#000000">;</span><br/>
- <span style="color:#ffffff"> </span><span
- style="color:#000000">sink.paragraph_</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">...</span><br/>
- <span style="color:#ffffff"></span><br/>
- <span style="color:#ffffff"> </span><span
style="color:#000000">sink.body_</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">sink.flush</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">sink.close</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>
