Skip to content

Commit 87529de

Browse files
garydgregorygarydgregory
committed
Javadoc
1 parent 47ff95d commit 87529de

1 file changed

Lines changed: 108 additions & 18 deletions

File tree

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

Lines changed: 108 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -313,9 +313,34 @@ public Builder setAutoFlush(final boolean autoFlush) {
313313
}
314314

315315
/**
316-
* Sets the comment start marker, use {@code null} to disable.
317-
*
318-
* Note that the comment start character is only recognized at the start of a line.
316+
* Sets the comment marker character, use {@code null} to disable comments.
317+
* <p>
318+
* The comment start character is only recognized at the start of a line.
319+
* </p>
320+
* <p>
321+
* Comments are printed first, before headers.
322+
* </p>
323+
* <p>
324+
* Use {@link #setCommentMarker(char)} or {@link #setCommentMarker(Character)} to set the comment marker written at the start of
325+
* each comment line.
326+
* </p>
327+
* <p>
328+
* If the comment marker is not set, then the header comments are ignored.
329+
* </p>
330+
* <p>
331+
* For example:
332+
* </p>
333+
* <pre>
334+
* builder.setCommentMarker('#')
335+
* .setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0));
336+
* </pre>
337+
* <p>
338+
* writes:
339+
* </p>
340+
* <pre>
341+
* # Generated by Apache Commons CSV.
342+
* # 1970-01-01T00:00:00Z
343+
* </pre>
319344
*
320345
* @param commentMarker the comment start marker, use {@code null} to disable.
321346
* @return This instance.
@@ -327,9 +352,34 @@ public Builder setCommentMarker(final char commentMarker) {
327352
}
328353

329354
/**
330-
* Sets the comment start marker, use {@code null} to disable.
331-
*
332-
* Note that the comment start character is only recognized at the start of a line.
355+
* Sets the comment marker character, use {@code null} to disable comments.
356+
* <p>
357+
* The comment start character is only recognized at the start of a line.
358+
* </p>
359+
* <p>
360+
* Comments are printed first, before headers.
361+
* </p>
362+
* <p>
363+
* Use {@link #setCommentMarker(char)} or {@link #setCommentMarker(Character)} to set the comment marker written at the start of
364+
* each comment line.
365+
* </p>
366+
* <p>
367+
* If the comment marker is not set, then the header comments are ignored.
368+
* </p>
369+
* <p>
370+
* For example:
371+
* </p>
372+
* <pre>
373+
* builder.setCommentMarker('#')
374+
* .setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0));
375+
* </pre>
376+
* <p>
377+
* writes:
378+
* </p>
379+
* <pre>
380+
* # Generated by Apache Commons CSV.
381+
* # 1970-01-01T00:00:00Z
382+
* </pre>
333383
*
334384
* @param commentMarker the comment start marker, use {@code null} to disable.
335385
* @return This instance.
@@ -521,15 +571,15 @@ public Builder setHeader(final String... header) {
521571
}
522572

523573
/**
524-
* Sets the header comments to the given values before the CSV data.
574+
* Sets the header comments to write before the CSV data.
525575
* <p>
526576
* This setting is ignored by the parser.
527577
* </p>
528578
* <p>
529579
* Comments are printed first, before headers.
530580
* </p>
531581
* <p>
532-
* Use {@link Builder#setCommentMarker(char)} or {@link Builder#setCommentMarker(Character)} to set the comment marker written at the start of
582+
* Use {@link #setCommentMarker(char)} or {@link #setCommentMarker(Character)} to set the comment marker written at the start of
533583
* each comment line.
534584
* </p>
535585
* <p>
@@ -553,22 +603,21 @@ public Builder setHeader(final String... header) {
553603
* @param headerComments the headerComments which will be printed by the Printer before the CSV data.
554604
* @return This instance.
555605
*/
556-
557606
public Builder setHeaderComments(final Object... headerComments) {
558607
this.headerComments = CSVFormat.clone(toStringArray(headerComments));
559608
return this;
560609
}
561610

562611
/**
563-
* Sets the header comments to the given values before the CSV data.
612+
* Sets the header comments to write before the CSV data.
564613
* <p>
565614
* This setting is ignored by the parser.
566615
* </p>
567616
* <p>
568617
* Comments are printed first, before headers.
569618
* </p>
570619
* <p>
571-
* Use {@link Builder#setCommentMarker(char)} or {@link Builder#setCommentMarker(Character)} to set the comment marker written at the start of
620+
* Use {@link #setCommentMarker(char)} or {@link #setCommentMarker(Character)} to set the comment marker written at the start of
572621
* each comment line.
573622
* </p>
574623
* <p>
@@ -1570,19 +1619,33 @@ public boolean getAutoFlush() {
15701619
}
15711620

15721621
/**
1573-
* Gets the character marking the start of a line comment.
1622+
* Gets the comment marker character, {@code null} disables comments.
1623+
* <p>
1624+
* The comment start character is only recognized at the start of a line.
1625+
* </p>
1626+
* <p>
1627+
* Comments are printed first, before headers.
1628+
* </p>
1629+
* <p>
1630+
* Use {@link Builder#setCommentMarker(char)} or {@link Builder#setCommentMarker(Character)} to set the comment
1631+
* marker written at the start of each comment line.
1632+
* </p>
15741633
* <p>
1575-
* The comment format for each line is:
1634+
* If the comment marker is not set, then the header comments are ignored.
1635+
* </p>
1636+
* <p>
1637+
* For example:
15761638
* </p>
15771639
* <pre>
1578-
* CommentMarker SPACE CommentArrayElement
1640+
* builder.setCommentMarker('#')
1641+
* .setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0));
15791642
* </pre>
15801643
* <p>
1581-
* For example, using a comment marker {@code '#'} and a comment array {@code comments ["line 1", "line 2"]}:
1644+
* writes:
15821645
* </p>
15831646
* <pre>
1584-
* # line 1
1585-
* # line 2
1647+
* # Generated by Apache Commons CSV.
1648+
* # 1970-01-01T00:00:00Z
15861649
* </pre>
15871650
*
15881651
* @return the comment start marker, may be {@code null}
@@ -1641,7 +1704,34 @@ public String[] getHeader() {
16411704
}
16421705

16431706
/**
1644-
* Gets a copy of the header comment array.
1707+
* Gets a copy of the header comment array to write before the CSV data.
1708+
* <p>
1709+
* This setting is ignored by the parser.
1710+
* </p>
1711+
* <p>
1712+
* Comments are printed first, before headers.
1713+
* </p>
1714+
* <p>
1715+
* Use {@link Builder#setCommentMarker(char)} or {@link Builder#setCommentMarker(Character)} to set the comment
1716+
* marker written at the start of each comment line.
1717+
* </p>
1718+
* <p>
1719+
* If the comment marker is not set, then the header comments are ignored.
1720+
* </p>
1721+
* <p>
1722+
* For example:
1723+
* </p>
1724+
* <pre>
1725+
* builder.setCommentMarker('#')
1726+
* .setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0));
1727+
* </pre>
1728+
* <p>
1729+
* writes:
1730+
* </p>
1731+
* <pre>
1732+
* # Generated by Apache Commons CSV.
1733+
* # 1970-01-01T00:00:00Z
1734+
* </pre>
16451735
*
16461736
* @return a copy of the header comment array; {@code null} if disabled.
16471737
*/

0 commit comments

Comments
 (0)