This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-cli.git
The following commit(s) were added to refs/heads/master by this push:
new 107c822f Javadoc
107c822f is described below
commit 107c822f34ec25ddcdfb199ba255444cacec516f
Author: Gary Gregory <garydgreg...@gmail.com>
AuthorDate: Sat Oct 19 07:56:41 2024 -0400
Javadoc
Prevent NPEs per Javadoc contract
---
.../apache/commons/cli/help/HelpAppendable.java | 35 ++++++++------
.../commons/cli/example/AptHelpAppendable.java | 4 +-
.../commons/cli/example/XhtmlHelpAppendable.java | 54 ++++++++++++----------
3 files changed, 53 insertions(+), 40 deletions(-)
diff --git a/src/main/java/org/apache/commons/cli/help/HelpAppendable.java
b/src/main/java/org/apache/commons/cli/help/HelpAppendable.java
index 78186be9..5d88c04d 100644
--- a/src/main/java/org/apache/commons/cli/help/HelpAppendable.java
+++ b/src/main/java/org/apache/commons/cli/help/HelpAppendable.java
@@ -19,6 +19,7 @@ package org.apache.commons.cli.help;
import java.io.IOException;
import java.util.Collection;
import java.util.Formatter;
+import java.util.IllegalFormatException;
/**
* Defines a semantic scribe. The semantic scribe appends text to an output
based on the semantic meaning of the type of string. For example, a Paragraph
versus
@@ -38,16 +39,17 @@ public interface HelpAppendable extends Appendable {
/**
* Appends a formatted string using the specified format string and
arguments.
* <p>
- * Short-hand for:
+ * Short-hand for calling:
* </p>
*
* <pre>
- * append(String.format(format, args));
+ * helpAppendable.{@link #append(CharSequence) append.}({@link
String#format(String, Object...) String.format}(format, args));
* </pre>
*
* @param format The format string for {@link String#format(String,
Object...)}.
* @param args Arguments to {@link String#format(String, Object...)}.
- * @throws IOException If an output error occurs
+ * @throws IllegalFormatException See {@link String#format(String,
Object...)}.
+ * @throws IOException If an output error occurs.
* @see String#format(String, Object...)
* @see Formatter
* @see #append(CharSequence)
@@ -60,8 +62,8 @@ public interface HelpAppendable extends Appendable {
* Appends a header.
*
* @param level the level of the header. This is equivalent to the "1",
"2", or "3" in the HTML "h1", "h2", "h3" tags.
- * @param text the text for the header
- * @throws IOException If an output error occurs
+ * @param text the text for the header, null is a noop.
+ * @throws IOException If an output error occurs.
*/
void appendHeader(int level, CharSequence text) throws IOException;
@@ -69,25 +71,30 @@ public interface HelpAppendable extends Appendable {
* Appends a list.
*
* @param ordered {@code true} if the list should be ordered.
- * @param list the list to write.
- * @throws IOException If an output error occurs
+ * @param list the list to write, null is a noop.
+ * @throws IOException If an output error occurs.
*/
void appendList(boolean ordered, Collection<CharSequence> list) throws
IOException;
/**
* Appends a paragraph.
*
- * @param paragraph the paragraph to write.
- * @throws IOException If an output error occurs
+ * @param paragraph the paragraph to write, null is a noop.
+ * @throws IOException If an output error occurs.
*/
void appendParagraph(CharSequence paragraph) throws IOException;
/**
* Appends a formatted string as a paragraph.
*
+ * <pre>
+ * helpAppendable.{@link #appendParagraph(CharSequence)
appendParagraph.}({@link String#format(String, Object...)
String.format}(format, args));
+ * </pre>
+ *
* @param format The format string for {@link String#format(String,
Object...)}.
* @param args Arguments to {@link String#format(String, Object...)}.
- * @throws IOException If an output error occurs
+ * @throws IllegalFormatException See {@link String#format(String,
Object...)}.
+ * @throws IOException If an output error occurs.
* @see String#format(String, Object...)
* @see Formatter
* @see #append(CharSequence)
@@ -99,16 +106,16 @@ public interface HelpAppendable extends Appendable {
/**
* Appends a table.
*
- * @param table the table definition to write.
- * @throws IOException If an output error occurs
+ * @param table the table definition to write, null is a noop.
+ * @throws IOException If an output error occurs.
*/
void appendTable(TableDefinition table) throws IOException;
/**
* Appends a title.
*
- * @param title the title to write.
- * @throws IOException If an output error occurs
+ * @param title the title to write, null is a noop.
+ * @throws IOException If an output error occurs.
*/
void appendTitle(CharSequence title) throws IOException;
diff --git
a/src/test/java/org/apache/commons/cli/example/AptHelpAppendable.java
b/src/test/java/org/apache/commons/cli/example/AptHelpAppendable.java
index 1114e2ab..d2e25bec 100644
--- a/src/test/java/org/apache/commons/cli/example/AptHelpAppendable.java
+++ b/src/test/java/org/apache/commons/cli/example/AptHelpAppendable.java
@@ -29,7 +29,7 @@ import
org.apache.commons.text.translate.CharSequenceTranslator;
import org.apache.commons.text.translate.LookupTranslator;
/**
- * A class to write APT formatted text.
+ * Appends APT formatted text to an {@link Appendable}.
*/
public class AptHelpAppendable extends FilterHelpAppendable {
@@ -73,7 +73,7 @@ public class AptHelpAppendable extends FilterHelpAppendable {
@Override
public void appendList(final boolean ordered, final
Collection<CharSequence> list) throws IOException {
- if (null != list) {
+ if (list != null) {
if (ordered) {
int idx = 1;
for (final CharSequence s : list) {
diff --git
a/src/test/java/org/apache/commons/cli/example/XhtmlHelpAppendable.java
b/src/test/java/org/apache/commons/cli/example/XhtmlHelpAppendable.java
index 1a398790..47e08f59 100644
--- a/src/test/java/org/apache/commons/cli/example/XhtmlHelpAppendable.java
+++ b/src/test/java/org/apache/commons/cli/example/XhtmlHelpAppendable.java
@@ -27,7 +27,7 @@ import org.apache.commons.lang3.StringUtils;
import org.apache.commons.text.StringEscapeUtils;
/**
- * A class to write XHTML formatted text.
+ * Appends XHTML formatted text to an {@link Appendable}.
*/
public class XhtmlHelpAppendable extends FilterHelpAppendable {
@@ -53,11 +53,13 @@ public class XhtmlHelpAppendable extends
FilterHelpAppendable {
@Override
public void appendList(final boolean ordered, final
Collection<CharSequence> list) throws IOException {
- appendFormat("<%sl>%n", ordered ? "o" : "u");
- for (final CharSequence line : list) {
- appendFormat(" <li>%s</li>%n",
StringEscapeUtils.escapeHtml4(StringUtils.defaultIfEmpty(line, "").toString()));
+ if (list != null) {
+ appendFormat("<%sl>%n", ordered ? "o" : "u");
+ for (final CharSequence line : list) {
+ appendFormat(" <li>%s</li>%n",
StringEscapeUtils.escapeHtml4(StringUtils.defaultIfEmpty(line, "").toString()));
+ }
+ appendFormat("</%sl>%n", ordered ? "o" : "u");
}
- appendFormat("</%sl>%n", ordered ? "o" : "u");
}
@Override
@@ -69,31 +71,35 @@ public class XhtmlHelpAppendable extends
FilterHelpAppendable {
@Override
public void appendTable(final TableDefinition table) throws IOException {
- appendFormat("<table class='commons_cli_table'>%n");
- if (StringUtils.isNotEmpty(table.caption())) {
- appendFormat(" <caption>%s</caption>%n",
StringEscapeUtils.escapeHtml4(table.caption()));
- }
- // write the headers
- if (!table.headers().isEmpty()) {
- appendFormat(" <tr>%n");
- for (final String header : table.headers()) {
- appendFormat(" <th>%s</th>%n",
StringEscapeUtils.escapeHtml4(header));
+ if (table != null) {
+ appendFormat("<table class='commons_cli_table'>%n");
+ if (StringUtils.isNotEmpty(table.caption())) {
+ appendFormat(" <caption>%s</caption>%n",
StringEscapeUtils.escapeHtml4(table.caption()));
}
- appendFormat(" </tr>%n");
- }
- // write the data
- for (final List<String> row : table.rows()) {
- appendFormat(" <tr>%n");
- for (final String column : row) {
- appendFormat(" <td>%s</td>%n",
StringEscapeUtils.escapeHtml4(column));
+ // write the headers
+ if (!table.headers().isEmpty()) {
+ appendFormat(" <tr>%n");
+ for (final String header : table.headers()) {
+ appendFormat(" <th>%s</th>%n",
StringEscapeUtils.escapeHtml4(header));
+ }
+ appendFormat(" </tr>%n");
}
- appendFormat(" </tr>%n");
+ // write the data
+ for (final List<String> row : table.rows()) {
+ appendFormat(" <tr>%n");
+ for (final String column : row) {
+ appendFormat(" <td>%s</td>%n",
StringEscapeUtils.escapeHtml4(column));
+ }
+ appendFormat(" </tr>%n");
+ }
+ appendFormat("</table>%n");
}
- appendFormat("</table>%n");
}
@Override
public void appendTitle(final CharSequence title) throws IOException {
- appendFormat("<span class='commons_cli_title'>%s</span>%n",
StringEscapeUtils.escapeHtml4(Objects.toString(title)));
+ if (StringUtils.isNotEmpty(title)) {
+ appendFormat("<span class='commons_cli_title'>%s</span>%n",
StringEscapeUtils.escapeHtml4(Objects.toString(title)));
+ }
}
}
