From 107c822f34ec25ddcdfb199ba255444cacec516f Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Sat, 19 Oct 2024 07:56:41 -0400 Subject: [PATCH] Javadoc Prevent NPEs per Javadoc contract --- .../commons/cli/help/HelpAppendable.java | 35 +++++++----- .../cli/example/AptHelpAppendable.java | 4 +- .../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 78186be9e..5d88c04da 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 @@ Licensed to the Apache Software Foundation (ASF) under one or more 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. *

- * Short-hand for: + * Short-hand for calling: *

* * 
-     * append(String.format(format, args));
+     * helpAppendable.{@link #append(CharSequence) append.}({@link String#format(String, Object...) String.format}(format, args));
      *
* * @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 @@ default void appendFormat(final String format, final Object... args) throws IOEx * 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 @@ default void appendFormat(final String format, final Object... args) throws IOEx * 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 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. * + * 
+     * helpAppendable.{@link #appendParagraph(CharSequence) appendParagraph.}({@link String#format(String, Object...) String.format}(format, args));
+     *
+ * * @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 @@ default void appendParagraphFormat(final String format, final Object... args) th /** * 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 1114e2ab7..d2e25bece 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 @@ Licensed to the Apache Software Foundation (ASF) under one or more 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 void appendHeader(final int level, final CharSequence text) throws IOExce @Override public void appendList(final boolean ordered, final Collection 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 1a398790a..47e08f59b 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 @@ Licensed to the Apache Software Foundation (ASF) under one or more 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 void appendHeader(final int level, final CharSequence text) throws IOExce @Override public void appendList(final boolean ordered, final Collection list) throws IOException { - appendFormat("<%sl>%n", ordered ? "o" : "u"); - for (final CharSequence line : list) { - appendFormat("
  • %s
    • %n", StringEscapeUtils.escapeHtml4(StringUtils.defaultIfEmpty(line, "").toString())); + if (list != null) { + appendFormat("<%sl>%n", ordered ? "o" : "u"); + for (final CharSequence line : list) { + appendFormat("
  • %s
    • %n", StringEscapeUtils.escapeHtml4(StringUtils.defaultIfEmpty(line, "").toString())); + } + appendFormat("%n", ordered ? "o" : "u"); } - appendFormat("%n", ordered ? "o" : "u"); } @Override @@ -69,31 +71,35 @@ public void appendParagraph(final CharSequence paragraph) throws IOException { @Override public void appendTable(final TableDefinition table) throws IOException { - appendFormat("%n"); - if (StringUtils.isNotEmpty(table.caption())) { - appendFormat(" %n", StringEscapeUtils.escapeHtml4(table.caption())); - } - // write the headers - if (!table.headers().isEmpty()) { - appendFormat(" %n"); - for (final String header : table.headers()) { - appendFormat(" %n", StringEscapeUtils.escapeHtml4(header)); + if (table != null) { + appendFormat("
    %s
    %s
    %n"); + if (StringUtils.isNotEmpty(table.caption())) { + appendFormat(" %n", StringEscapeUtils.escapeHtml4(table.caption())); } - appendFormat(" %n"); - } - // write the data - for (final List row : table.rows()) { - appendFormat(" %n"); - for (final String column : row) { - appendFormat(" %n", StringEscapeUtils.escapeHtml4(column)); + // write the headers + if (!table.headers().isEmpty()) { + appendFormat(" %n"); + for (final String header : table.headers()) { + appendFormat(" %n", StringEscapeUtils.escapeHtml4(header)); + } + appendFormat(" %n"); } - appendFormat(" %n"); + // write the data + for (final List row : table.rows()) { + appendFormat(" %n"); + for (final String column : row) { + appendFormat(" %n", StringEscapeUtils.escapeHtml4(column)); + } + appendFormat(" %n"); + } + appendFormat("
    %s
    %s
    %s
    %s
    %n"); } - appendFormat("%n"); } @Override public void appendTitle(final CharSequence title) throws IOException { - appendFormat("%s%n", StringEscapeUtils.escapeHtml4(Objects.toString(title))); + if (StringUtils.isNotEmpty(title)) { + appendFormat("%s%n", StringEscapeUtils.escapeHtml4(Objects.toString(title))); + } } }