[CSV-161] Fix Javadoc to say CSVFormat with() methods return a new CSVFormat.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/csv/trunk@1725409 13f79535-47bb-0310-9956-ffa450edef68

Author: garydgregory

src/changes/changes.xml

@@ -44,6 +44,7 @@
       <action issue="CSV-169" type="add" dev="ggregory" due-to="Gary Gregory">The null string should be case-sensitive when reading records</action>
       <action issue="CSV-168" type="fix" dev="ggregory" due-to="Gary Gregory, cornel creanga">CsvFormat.nullString should not be escaped</action>
       <action issue="CSV-170" type="fix" dev="ggregory" due-to="Gary Gregory, cornel creanga">CSVFormat.MYSQL nullString should be "\N"</action>
+      <action issue="CSV-161" type="fix" dev="ggregory" due-to="Gary Gregory, Kristof Meixner, Emmanuel Bourg">Fix Javadoc to say CSVFormat with() methods return a new CSVFormat</action>
     </release>
     <release version="1.2" date="2015-08-24" description="Feature and bug fix release">
       <action issue="CSV-145" type="fix" dev="ggregory" due-to="Frank Ulbricht">CSVFormat.with* methods clear the header comments</action>

src/main/java/org/apache/commons/csv/CSVFormat.java

@@ -857,7 +857,7 @@ private void validate() throws IllegalArgumentException {
     }
 
     /**
-     * Sets the comment start marker of the format to the specified character.
+     * Returns a new {@code CSVFormat} with the comment start marker of the format set to the specified character.
      *
      * Note that the comment start character is only recognized at the start of a line.
      *
@@ -872,7 +872,7 @@ public CSVFormat withCommentMarker(final char commentMarker) {
     }
 
     /**
-     * Sets the comment start marker of the format to the specified character.
+     * Returns a new {@code CSVFormat} with the comment start marker of the format set to the specified character.
      *
      * Note that the comment start character is only recognized at the start of a line.
      *
@@ -892,7 +892,7 @@ public CSVFormat withCommentMarker(final Character commentMarker) {
     }
 
     /**
-     * Sets the delimiter of the format to the specified character.
+     * Returns a new {@code CSVFormat} with the delimiter of the format set to the specified character.
      *
      * @param delimiter
      *            the delimiter character
@@ -910,7 +910,7 @@ public CSVFormat withDelimiter(final char delimiter) {
     }
 
     /**
-     * Sets the escape character of the format to the specified character.
+     * Returns a new {@code CSVFormat} with the escape character of the format set to the specified character.
      *
      * @param escape
      *            the escape character
@@ -923,7 +923,7 @@ public CSVFormat withEscape(final char escape) {
     }
 
     /**
-     * Sets the escape character of the format to the specified character.
+     * Returns a new {@code CSVFormat} with the escape character of the format set to the specified character.
      *
      * @param escape
      *            the escape character, use {@code null} to disable
@@ -941,7 +941,8 @@ public CSVFormat withEscape(final Character escape) {
     }
 
     /**
-     * Sets the header of the format. The header can either be parsed automatically from the input file with:
+     * Returns a new {@code CSVFormat} with the header of the format set to the given values. 
+     * The header can either be parsed automatically from the input file with:
      *
      * <pre>
      * CSVFormat format = aformat.withHeader();
@@ -969,7 +970,8 @@ public CSVFormat withHeader(final String... header) {
     }
 
     /**
-     * Sets the header of the format. The header can either be parsed automatically from the input file with:
+     * Returns a new {@code CSVFormat} with the header of the format set from the result set metadata. 
+     * The header can either be parsed automatically from the input file with:
      *
      * <pre>
      * CSVFormat format = aformat.withHeader();
@@ -998,7 +1000,8 @@ public CSVFormat withHeader(final ResultSet resultSet) throws SQLException {
     }
 
     /**
-     * Sets the header of the format. The header can either be parsed automatically from the input file with:
+     * Returns a new {@code CSVFormat} with the header of the format set from the result set metadata.
+     *  The header can either be parsed automatically from the input file with:
      *
      * <pre>
      * CSVFormat format = aformat.withHeader();
@@ -1037,8 +1040,8 @@ public CSVFormat withHeader(final ResultSetMetaData metaData) throws SQLExceptio
     }
 
     /**
-     * Sets the header comments of the format. The comments will be printed first, before the headers. This setting is
-     * ignored by the parser.
+     * Returns a new {@code CSVFormat} with the header comments of the format set to the given values. 
+     * The comments will be printed first, before the headers. This setting is ignored by the parser.
      *
      * <pre>
      * CSVFormat format = aformat.withHeaderComments(&quot;Generated by Apache Commons CSV 1.1.&quot;, new Date());
@@ -1058,7 +1061,7 @@ public CSVFormat withHeaderComments(final Object... headerComments) {
     }
 
     /**
-     * Sets the missing column names behavior of the format to {@code true}
+     * Returns a new {@code CSVFormat} with the missing column names behavior of the format set to {@code true}
      *
      * @return A new CSVFormat that is equal to this but with the specified missing column names behavior.
      * @see #withAllowMissingColumnNames(boolean)
@@ -1069,7 +1072,7 @@ public CSVFormat withAllowMissingColumnNames() {
     }
 
     /**
-     * Sets the missing column names behavior of the format.
+     * Returns a new {@code CSVFormat} with the missing column names behavior of the format set to the given value.
      *
      * @param allowMissingColumnNames
      *            the missing column names behavior, {@code true} to allow missing column names in the header line,
@@ -1083,7 +1086,7 @@ public CSVFormat withAllowMissingColumnNames(final boolean allowMissingColumnNam
     }
 
     /**
-     * Sets the empty line skipping behavior of the format to {@code true}.
+     * Returns a new {@code CSVFormat} with the empty line skipping behavior of the format set to {@code true}.
      *
      * @return A new CSVFormat that is equal to this but with the specified empty line skipping behavior.
      * @since {@link #withIgnoreEmptyLines(boolean)}
@@ -1094,7 +1097,7 @@ public CSVFormat withIgnoreEmptyLines() {
     }
 
     /**
-     * Sets the empty line skipping behavior of the format.
+     * Returns a new {@code CSVFormat} with the empty line skipping behavior of the format set to the given value.
      *
      * @param ignoreEmptyLines
      *            the empty line skipping behavior, {@code true} to ignore the empty lines between the records,
@@ -1108,7 +1111,7 @@ public CSVFormat withIgnoreEmptyLines(final boolean ignoreEmptyLines) {
     }
 
     /**
-     * Sets the trimming behavior of the format to {@code true}.
+     * Returns a new {@code CSVFormat} with the trimming behavior of the format set to {@code true}.
      *
      * @return A new CSVFormat that is equal to this but with the specified trimming behavior.
      * @see #withIgnoreSurroundingSpaces(boolean)
@@ -1119,7 +1122,7 @@ public CSVFormat withIgnoreSurroundingSpaces() {
     }
 
     /**
-     * Sets the trimming behavior of the format.
+     * Returns a new {@code CSVFormat} with the trimming behavior of the format set to the given value.
      *
      * @param ignoreSurroundingSpaces
      *            the trimming behavior, {@code true} to remove the surrounding spaces, {@code false} to leave the
@@ -1133,7 +1136,7 @@ public CSVFormat withIgnoreSurroundingSpaces(final boolean ignoreSurroundingSpac
     }
 
     /**
-     * Sets the header ignore case behavior to {@code true}.
+     * Returns a new {@code CSVFormat} with the header ignore case behavior set to {@code true}.
      *
      * @return A new CSVFormat that will ignore case header name.
      * @see #withIgnoreHeaderCase(boolean)
@@ -1144,7 +1147,7 @@ public CSVFormat withIgnoreHeaderCase() {
     }
 
     /**
-     * Sets if header names should be accessed ignoring case.
+     * Returns a new {@code CSVFormat} with whether header names should be accessed ignoring case.
      *
      * @param ignoreHeaderCase
      *            the case mapping behavior, {@code true} to access name/values, {@code false} to leave the
@@ -1158,7 +1161,7 @@ public CSVFormat withIgnoreHeaderCase(final boolean ignoreHeaderCase) {
     }
 
     /**
-     * Performs conversions to and from null for strings on input and output.
+     * Returns a new {@code CSVFormat} with conversions to and from null for strings on input and output.
      * <ul>
      * <li>
      * <strong>Reading:</strong> Converts strings equal to the given {@code nullString} to {@code null} when reading
@@ -1179,7 +1182,7 @@ public CSVFormat withNullString(final String nullString) {
     }
 
     /**
-     * Sets the quoteChar of the format to the specified character.
+     * Returns a new {@code CSVFormat} with the quoteChar of the format set to the specified character.
      *
      * @param quoteChar
      *            the quoteChar character
@@ -1192,7 +1195,7 @@ public CSVFormat withQuote(final char quoteChar) {
     }
 
     /**
-     * Sets the quoteChar of the format to the specified character.
+     * Returns a new {@code CSVFormat} with the quoteChar of the format set to the specified character.
      *
      * @param quoteChar
      *            the quoteChar character, use {@code null} to disable
@@ -1210,7 +1213,7 @@ public CSVFormat withQuote(final Character quoteChar) {
     }
 
     /**
-     * Sets the output quote policy of the format to the specified value.
+     * Returns a new {@code CSVFormat} with the output quote policy of the format set to the specified value.
      *
      * @param quoteModePolicy
      *            the quote policy to use for output.
@@ -1224,7 +1227,7 @@ public CSVFormat withQuoteMode(final QuoteMode quoteModePolicy) {
     }
 
     /**
-     * Sets the record separator of the format to the specified character.
+     * Returns a new {@code CSVFormat} with the record separator of the format set to the specified character.
      *
      * <p>
      * <strong>Note:</strong> This setting is only used during printing and does not affect parsing. Parsing currently
@@ -1241,7 +1244,7 @@ public CSVFormat withRecordSeparator(final char recordSeparator) {
     }
 
     /**
-     * Sets the record separator of the format to the specified String.
+     * Returns a new {@code CSVFormat} with the record separator of the format set to the specified String.
      *
      * <p>
      * <strong>Note:</strong> This setting is only used during printing and does not affect parsing. Parsing currently
@@ -1262,7 +1265,7 @@ public CSVFormat withRecordSeparator(final String recordSeparator) {
     }
 
     /**
-     * Sets skipping the header record to {@code true}.
+     * Returns a new {@code CSVFormat} with skipping the header record set to {@code true}.
      *
      * @return A new CSVFormat that is equal to this but with the the specified skipHeaderRecord setting.
      * @see #withSkipHeaderRecord(boolean)
@@ -1274,7 +1277,7 @@ public CSVFormat withSkipHeaderRecord() {
     }
 
     /**
-     * Sets whether to skip the header record.
+     * Returns a new {@code CSVFormat} with whether to skip the header record.
      *
      * @param skipHeaderRecord
      *            whether to skip the header record.