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-csv.git
The following commit(s) were added to refs/heads/master by this push:
new 87529dea Javadoc
87529dea is described below
commit 87529dea16bd7f20f6b7e8d3597689ad6043156e
Author: Gary Gregory <[email protected]>
AuthorDate: Sat Aug 26 08:06:55 2023 -0400
Javadoc
---
.../java/org/apache/commons/csv/CSVFormat.java | 126 ++++++++++++++++++---
1 file changed, 108 insertions(+), 18 deletions(-)
diff --git a/src/main/java/org/apache/commons/csv/CSVFormat.java
b/src/main/java/org/apache/commons/csv/CSVFormat.java
index 7cb542cd..b3ac7ace 100644
--- a/src/main/java/org/apache/commons/csv/CSVFormat.java
+++ b/src/main/java/org/apache/commons/csv/CSVFormat.java
@@ -313,9 +313,34 @@ public final class CSVFormat implements Serializable {
}
/**
- * Sets the comment start marker, use {@code null} to disable.
- *
- * Note that the comment start character is only recognized at the
start of a line.
+ * Sets the comment marker character, use {@code null} to disable
comments.
+ * <p>
+ * The comment start character is only recognized at the start of a
line.
+ * </p>
+ * <p>
+ * Comments are printed first, before headers.
+ * </p>
+ * <p>
+ * Use {@link #setCommentMarker(char)} or {@link
#setCommentMarker(Character)} to set the comment marker written at the start of
+ * each comment line.
+ * </p>
+ * <p>
+ * If the comment marker is not set, then the header comments are
ignored.
+ * </p>
+ * <p>
+ * For example:
+ * </p>
+ * <pre>
+ * builder.setCommentMarker('#')
+ * .setHeaderComments("Generated by Apache Commons CSV",
Instant.ofEpochMilli(0));
+ * </pre>
+ * <p>
+ * writes:
+ * </p>
+ * <pre>
+ * # Generated by Apache Commons CSV.
+ * # 1970-01-01T00:00:00Z
+ * </pre>
*
* @param commentMarker the comment start marker, use {@code null} to
disable.
* @return This instance.
@@ -327,9 +352,34 @@ public final class CSVFormat implements Serializable {
}
/**
- * Sets the comment start marker, use {@code null} to disable.
- *
- * Note that the comment start character is only recognized at the
start of a line.
+ * Sets the comment marker character, use {@code null} to disable
comments.
+ * <p>
+ * The comment start character is only recognized at the start of a
line.
+ * </p>
+ * <p>
+ * Comments are printed first, before headers.
+ * </p>
+ * <p>
+ * Use {@link #setCommentMarker(char)} or {@link
#setCommentMarker(Character)} to set the comment marker written at the start of
+ * each comment line.
+ * </p>
+ * <p>
+ * If the comment marker is not set, then the header comments are
ignored.
+ * </p>
+ * <p>
+ * For example:
+ * </p>
+ * <pre>
+ * builder.setCommentMarker('#')
+ * .setHeaderComments("Generated by Apache Commons CSV",
Instant.ofEpochMilli(0));
+ * </pre>
+ * <p>
+ * writes:
+ * </p>
+ * <pre>
+ * # Generated by Apache Commons CSV.
+ * # 1970-01-01T00:00:00Z
+ * </pre>
*
* @param commentMarker the comment start marker, use {@code null} to
disable.
* @return This instance.
@@ -521,7 +571,7 @@ public final class CSVFormat implements Serializable {
}
/**
- * Sets the header comments to the given values before the CSV data.
+ * Sets the header comments to write before the CSV data.
* <p>
* This setting is ignored by the parser.
* </p>
@@ -529,7 +579,7 @@ public final class CSVFormat implements Serializable {
* Comments are printed first, before headers.
* </p>
* <p>
- * Use {@link Builder#setCommentMarker(char)} or {@link
Builder#setCommentMarker(Character)} to set the comment marker written at the
start of
+ * Use {@link #setCommentMarker(char)} or {@link
#setCommentMarker(Character)} to set the comment marker written at the start of
* each comment line.
* </p>
* <p>
@@ -553,14 +603,13 @@ public final class CSVFormat implements Serializable {
* @param headerComments the headerComments which will be printed by
the Printer before the CSV data.
* @return This instance.
*/
-
public Builder setHeaderComments(final Object... headerComments) {
this.headerComments =
CSVFormat.clone(toStringArray(headerComments));
return this;
}
/**
- * Sets the header comments to the given values before the CSV data.
+ * Sets the header comments to write before the CSV data.
* <p>
* This setting is ignored by the parser.
* </p>
@@ -568,7 +617,7 @@ public final class CSVFormat implements Serializable {
* Comments are printed first, before headers.
* </p>
* <p>
- * Use {@link Builder#setCommentMarker(char)} or {@link
Builder#setCommentMarker(Character)} to set the comment marker written at the
start of
+ * Use {@link #setCommentMarker(char)} or {@link
#setCommentMarker(Character)} to set the comment marker written at the start of
* each comment line.
* </p>
* <p>
@@ -1570,19 +1619,33 @@ public final class CSVFormat implements Serializable {
}
/**
- * Gets the character marking the start of a line comment.
+ * Gets the comment marker character, {@code null} disables comments.
+ * <p>
+ * The comment start character is only recognized at the start of a line.
+ * </p>
+ * <p>
+ * Comments are printed first, before headers.
+ * </p>
+ * <p>
+ * Use {@link Builder#setCommentMarker(char)} or {@link
Builder#setCommentMarker(Character)} to set the comment
+ * marker written at the start of each comment line.
+ * </p>
* <p>
- * The comment format for each line is:
+ * If the comment marker is not set, then the header comments are ignored.
+ * </p>
+ * <p>
+ * For example:
* </p>
* <pre>
- * CommentMarker SPACE CommentArrayElement
+ * builder.setCommentMarker('#')
+ * .setHeaderComments("Generated by Apache Commons CSV",
Instant.ofEpochMilli(0));
* </pre>
* <p>
- * For example, using a comment marker {@code '#'} and a comment array
{@code comments ["line 1", "line 2"]}:
+ * writes:
* </p>
* <pre>
- * # line 1
- * # line 2
+ * # Generated by Apache Commons CSV.
+ * # 1970-01-01T00:00:00Z
* </pre>
*
* @return the comment start marker, may be {@code null}
@@ -1641,7 +1704,34 @@ public final class CSVFormat implements Serializable {
}
/**
- * Gets a copy of the header comment array.
+ * Gets a copy of the header comment array to write before the CSV data.
+ * <p>
+ * This setting is ignored by the parser.
+ * </p>
+ * <p>
+ * Comments are printed first, before headers.
+ * </p>
+ * <p>
+ * Use {@link Builder#setCommentMarker(char)} or {@link
Builder#setCommentMarker(Character)} to set the comment
+ * marker written at the start of each comment line.
+ * </p>
+ * <p>
+ * If the comment marker is not set, then the header comments are ignored.
+ * </p>
+ * <p>
+ * For example:
+ * </p>
+ * <pre>
+ * builder.setCommentMarker('#')
+ * .setHeaderComments("Generated by Apache Commons CSV",
Instant.ofEpochMilli(0));
+ * </pre>
+ * <p>
+ * writes:
+ * </p>
+ * <pre>
+ * # Generated by Apache Commons CSV.
+ * # 1970-01-01T00:00:00Z
+ * </pre>
*
* @return a copy of the header comment array; {@code null} if disabled.
*/
