Merge pull request apache#344 from gbidsilva/javaDocOptimization

[Javadoc] CSVFormat#setHeaderComments()

Author: garydgregory

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

@@ -521,28 +521,75 @@ public Builder setHeader(final String... header) {
         }
 
         /**
-         * Sets the header comments set to the given values. The comments will be printed first, before the headers. This setting is ignored by the parser.
-         *
+         * Sets the header comments to the given values 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>
-         * builder.setHeaderComments(&quot;Generated by Apache Commons CSV.&quot;, Instant.now());
+         * # Generated by Apache Commons CSV.
+         * # 1970-01-01T00:00:00Z
          * </pre>
          *
-         * @param headerComments the headerComments which will be printed by the Printer before the actual CSV data.
+         * @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 set to the given values. The comments will be printed first, before the headers. This setting is ignored by the parser.
-         *
+         * Sets the header comments to the given values 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).toString());
+         * </pre>
+         * <p>
+         * writes:
+         * </p>
          * <pre>
-         * Builder.setHeaderComments(&quot;Generated by Apache Commons CSV.&quot;, Instant.now());
+         * # Generated by Apache Commons CSV.
+         * # 1970-01-01T00:00:00Z
          * </pre>
          *
-         * @param headerComments the headerComments which will be printed by the Printer before the actual CSV data.
+         * @param headerComments the headerComments which will be printed by the Printer before the CSV data.
          * @return This instance.
          */
         public Builder setHeaderComments(final String... headerComments) {