Skip to content

Commit 107c822

Browse files
garydgregorygarydgregory
committed
Javadoc
Prevent NPEs per Javadoc contract
1 parent 252a587 commit 107c822

3 files changed

Lines changed: 53 additions & 40 deletions

File tree

‎src/main/java/org/apache/commons/cli/help/HelpAppendable.java‎

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
1919
import java.io.IOException;
2020
import java.util.Collection;
2121
import java.util.Formatter;
22+
import java.util.IllegalFormatException;
2223

2324
/**
2425
* 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 {
3839
/**
3940
* Appends a formatted string using the specified format string and arguments.
4041
* <p>
41-
* Short-hand for:
42+
* Short-hand for calling:
4243
* </p>
4344
*
4445
* <pre>
45-
* append(String.format(format, args));
46+
* helpAppendable.{@link #append(CharSequence) append.}({@link String#format(String, Object...) String.format}(format, args));
4647
* </pre>
4748
*
4849
* @param format The format string for {@link String#format(String, Object...)}.
4950
* @param args Arguments to {@link String#format(String, Object...)}.
50-
* @throws IOException If an output error occurs
51+
* @throws IllegalFormatException See {@link String#format(String, Object...)}.
52+
* @throws IOException If an output error occurs.
5153
* @see String#format(String, Object...)
5254
* @see Formatter
5355
* @see #append(CharSequence)
@@ -60,34 +62,39 @@ default void appendFormat(final String format, final Object... args) throws IOEx
6062
* Appends a header.
6163
*
6264
* @param level the level of the header. This is equivalent to the "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
63-
* @param text the text for the header
64-
* @throws IOException If an output error occurs
65+
* @param text the text for the header, null is a noop.
66+
* @throws IOException If an output error occurs.
6567
*/
6668
void appendHeader(int level, CharSequence text) throws IOException;
6769

6870
/**
6971
* Appends a list.
7072
*
7173
* @param ordered {@code true} if the list should be ordered.
72-
* @param list the list to write.
73-
* @throws IOException If an output error occurs
74+
* @param list the list to write, null is a noop.
75+
* @throws IOException If an output error occurs.
7476
*/
7577
void appendList(boolean ordered, Collection<CharSequence> list) throws IOException;
7678

7779
/**
7880
* Appends a paragraph.
7981
*
80-
* @param paragraph the paragraph to write.
81-
* @throws IOException If an output error occurs
82+
* @param paragraph the paragraph to write, null is a noop.
83+
* @throws IOException If an output error occurs.
8284
*/
8385
void appendParagraph(CharSequence paragraph) throws IOException;
8486

8587
/**
8688
* Appends a formatted string as a paragraph.
8789
*
90+
* <pre>
91+
* helpAppendable.{@link #appendParagraph(CharSequence) appendParagraph.}({@link String#format(String, Object...) String.format}(format, args));
92+
* </pre>
93+
*
8894
* @param format The format string for {@link String#format(String, Object...)}.
8995
* @param args Arguments to {@link String#format(String, Object...)}.
90-
* @throws IOException If an output error occurs
96+
* @throws IllegalFormatException See {@link String#format(String, Object...)}.
97+
* @throws IOException If an output error occurs.
9198
* @see String#format(String, Object...)
9299
* @see Formatter
93100
* @see #append(CharSequence)
@@ -99,16 +106,16 @@ default void appendParagraphFormat(final String format, final Object... args) th
99106
/**
100107
* Appends a table.
101108
*
102-
* @param table the table definition to write.
103-
* @throws IOException If an output error occurs
109+
* @param table the table definition to write, null is a noop.
110+
* @throws IOException If an output error occurs.
104111
*/
105112
void appendTable(TableDefinition table) throws IOException;
106113

107114
/**
108115
* Appends a title.
109116
*
110-
* @param title the title to write.
111-
* @throws IOException If an output error occurs
117+
* @param title the title to write, null is a noop.
118+
* @throws IOException If an output error occurs.
112119
*/
113120
void appendTitle(CharSequence title) throws IOException;
114121

‎src/test/java/org/apache/commons/cli/example/AptHelpAppendable.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
2929
import org.apache.commons.text.translate.LookupTranslator;
3030

3131
/**
32-
* A class to write APT formatted text.
32+
* Appends APT formatted text to an {@link Appendable}.
3333
*/
3434
public class AptHelpAppendable extends FilterHelpAppendable {
3535

@@ -73,7 +73,7 @@ public void appendHeader(final int level, final CharSequence text) throws IOExce
7373

7474
@Override
7575
public void appendList(final boolean ordered, final Collection<CharSequence> list) throws IOException {
76-
if (null != list) {
76+
if (list != null) {
7777
if (ordered) {
7878
int idx = 1;
7979
for (final CharSequence s : list) {

‎src/test/java/org/apache/commons/cli/example/XhtmlHelpAppendable.java‎

Lines changed: 30 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
2727
import org.apache.commons.text.StringEscapeUtils;
2828

2929
/**
30-
* A class to write XHTML formatted text.
30+
* Appends XHTML formatted text to an {@link Appendable}.
3131
*/
3232
public class XhtmlHelpAppendable extends FilterHelpAppendable {
3333

@@ -53,11 +53,13 @@ public void appendHeader(final int level, final CharSequence text) throws IOExce
5353

5454
@Override
5555
public void appendList(final boolean ordered, final Collection<CharSequence> list) throws IOException {
56-
appendFormat("<%sl>%n", ordered ? "o" : "u");
57-
for (final CharSequence line : list) {
58-
appendFormat(" <li>%s</li>%n", StringEscapeUtils.escapeHtml4(StringUtils.defaultIfEmpty(line, "").toString()));
56+
if (list != null) {
57+
appendFormat("<%sl>%n", ordered ? "o" : "u");
58+
for (final CharSequence line : list) {
59+
appendFormat(" <li>%s</li>%n", StringEscapeUtils.escapeHtml4(StringUtils.defaultIfEmpty(line, "").toString()));
60+
}
61+
appendFormat("</%sl>%n", ordered ? "o" : "u");
5962
}
60-
appendFormat("</%sl>%n", ordered ? "o" : "u");
6163
}
6264

6365
@Override
@@ -69,31 +71,35 @@ public void appendParagraph(final CharSequence paragraph) throws IOException {
6971

7072
@Override
7173
public void appendTable(final TableDefinition table) throws IOException {
72-
appendFormat("<table class='commons_cli_table'>%n");
73-
if (StringUtils.isNotEmpty(table.caption())) {
74-
appendFormat(" <caption>%s</caption>%n", StringEscapeUtils.escapeHtml4(table.caption()));
75-
}
76-
// write the headers
77-
if (!table.headers().isEmpty()) {
78-
appendFormat(" <tr>%n");
79-
for (final String header : table.headers()) {
80-
appendFormat(" <th>%s</th>%n", StringEscapeUtils.escapeHtml4(header));
74+
if (table != null) {
75+
appendFormat("<table class='commons_cli_table'>%n");
76+
if (StringUtils.isNotEmpty(table.caption())) {
77+
appendFormat(" <caption>%s</caption>%n", StringEscapeUtils.escapeHtml4(table.caption()));
8178
}
82-
appendFormat(" </tr>%n");
83-
}
84-
// write the data
85-
for (final List<String> row : table.rows()) {
86-
appendFormat(" <tr>%n");
87-
for (final String column : row) {
88-
appendFormat(" <td>%s</td>%n", StringEscapeUtils.escapeHtml4(column));
79+
// write the headers
80+
if (!table.headers().isEmpty()) {
81+
appendFormat(" <tr>%n");
82+
for (final String header : table.headers()) {
83+
appendFormat(" <th>%s</th>%n", StringEscapeUtils.escapeHtml4(header));
84+
}
85+
appendFormat(" </tr>%n");
8986
}
90-
appendFormat(" </tr>%n");
87+
// write the data
88+
for (final List<String> row : table.rows()) {
89+
appendFormat(" <tr>%n");
90+
for (final String column : row) {
91+
appendFormat(" <td>%s</td>%n", StringEscapeUtils.escapeHtml4(column));
92+
}
93+
appendFormat(" </tr>%n");
94+
}
95+
appendFormat("</table>%n");
9196
}
92-
appendFormat("</table>%n");
9397
}
9498

9599
@Override
96100
public void appendTitle(final CharSequence title) throws IOException {
97-
appendFormat("<span class='commons_cli_title'>%s</span>%n", StringEscapeUtils.escapeHtml4(Objects.toString(title)));
101+
if (StringUtils.isNotEmpty(title)) {
102+
appendFormat("<span class='commons_cli_title'>%s</span>%n", StringEscapeUtils.escapeHtml4(Objects.toString(title)));
103+
}
98104
}
99105
}

0 commit comments

Comments
 (0)