Skip to content

Commit

Permalink
Javadoc
Browse files Browse the repository at this point in the history 
Prevent NPEs per Javadoc contract
  • Loading branch information
@garydgregory
garydgregory committed Oct 19, 2024
1 parent 252a587 commit 107c822
Show file tree
Hide file tree
Showing 3 changed files with 53 additions and 40 deletions.
35 changes: 21 additions & 14 deletions src/main/java/org/apache/commons/cli/help/HelpAppendable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -60,34 +62,39 @@ 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;

/**
* 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)
Expand All @@ -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;

Expand Down
4 changes: 2 additions & 2 deletions src/test/java/org/apache/commons/cli/example/AptHelpAppendable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

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

@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) {
Expand Down
54 changes: 30 additions & 24 deletions src/test/java/org/apache/commons/cli/example/XhtmlHelpAppendable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

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

@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
Expand All @@ -69,31 +71,35 @@ public void appendParagraph(final CharSequence paragraph) throws IOException {

@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)));
}
}
}

0 comments on commit 107c822

Please sign in to comment.