Skip to content

Commit b4abb01

Browse files
gbidsilvagbidsilva
committed
Merge branch 'CSV-147' of https://github.com/gbidsilva/commons-csv-osc into CSV-147
2 parents 991763f + 1e8014b commit b4abb01

7 files changed

Lines changed: 177 additions & 25 deletions

File tree

‎.github/workflows/codeql-analysis.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ jobs:
4545

4646
steps:
4747
- name: Checkout repository
48-
uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
48+
uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744
4949
with:
5050
persist-credentials: false
5151
- uses: actions/cache@88522ab9f39a2ea568f7027eddc7d8d8bc9d59c8 # v3.3.1

‎.github/workflows/coverage.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ jobs:
2929
java: [ 8 ]
3030

3131
steps:
32-
- uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
32+
- uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744
3333
with:
3434
persist-credentials: false
3535
- uses: actions/cache@88522ab9f39a2ea568f7027eddc7d8d8bc9d59c8 # v3.3.1

‎.github/workflows/maven.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ jobs:
3434
# experimental: true
3535

3636
steps:
37-
- uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
37+
- uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744
3838
with:
3939
persist-credentials: false
4040
- uses: actions/cache@88522ab9f39a2ea568f7027eddc7d8d8bc9d59c8 # v3.3.1

‎.github/workflows/scorecards-analysis.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ jobs:
4040
steps:
4141

4242
- name: "Checkout code"
43-
uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # 3.5.3
43+
uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # 3.6.0
4444
with:
4545
persist-credentials: false
4646

‎pom.xml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
<parent>
2121
<groupId>org.apache.commons</groupId>
2222
<artifactId>commons-parent</artifactId>
23-
<version>59</version>
23+
<version>60</version>
2424
</parent>
2525
<artifactId>commons-csv</artifactId>
2626
<version>1.10.1-SNAPSHOT</version>
@@ -154,7 +154,7 @@
154154
<commons.release.version>1.10.0</commons.release.version>
155155
<commons.release.desc>(Java 8)</commons.release.desc>
156156
<!-- The RC version used in the staging repository URL. -->
157-
<commons.rc.version>RC2</commons.rc.version>
157+
<commons.rc.version>RC1</commons.rc.version>
158158
<commons.bc.version>1.9.0</commons.bc.version>
159159
<commons.componentid>csv</commons.componentid>
160160
<commons.module.name>org.apache.commons.csv</commons.module.name>
@@ -181,7 +181,7 @@
181181
</properties>
182182

183183
<build>
184-
<defaultGoal>clean verify apache-rat:check japicmp:cmp checkstyle:check spotbugs:check pmd:check pmd:cpd-check javadoc:javadoc</defaultGoal>
184+
<defaultGoal>clean verify apache-rat:check japicmp:cmp spotbugs:check pmd:check pmd:cpd-check javadoc:javadoc checkstyle:check</defaultGoal>
185185
<pluginManagement>
186186
<plugins>
187187
<plugin>

‎src/changes/changes.xml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,14 +41,16 @@
4141
</properties>
4242
<body>
4343
<release version="1.10.1" date="2023-MM-DD" description="Feature and bug fix release (Java 8)">
44+
<!-- ADD -->
45+
<action issue="CSV-308" type="fix" dev="ggregory" due-to="Buddhi De Silva, Gary Gregory">[Javadoc] Add example to CSVFormat#setHeaderComments() #344.</action>
4446
<!-- FIX -->
4547
<action issue="CSV-306" type="fix" dev="ggregory" due-to="Sam Ng, Bruno P. Kinoshita">Replace deprecated method in user guide, update external link #324, #325.</action>
4648
<action type="fix" dev="ggregory" due-to="Seth Falco, Bruno P. Kinoshita">Document duplicate header behavior #309.</action>
4749
<action type="fix" dev="ggregory" due-to="jkbkupczyk">Add missing docs #328.</action>
48-
<action type="fix" dev="ggregory" due-to="step-security-bot">[StepSecurity] ci: Harden GitHub Actions #329, #330.</action>
50+
<action type="fix" dev="ggregory" due-to="step-security-bot">[StepSecurity] CI: Harden GitHub Actions #329, #330.</action>
4951
<!-- UPDATE -->
5052
<action type="update" dev="ggregory" due-to="Gary Gregory">Bump commons-io:commons-io: from 2.11.0 to 2.13.0.</action>
51-
<action type="update" dev="ggregory" due-to="Gary Gregory">Bump commons-parent from 57 to 59.</action>
53+
<action type="update" dev="ggregory" due-to="Gary Gregory">Bump commons-parent from 57 to 60.</action>
5254
<action type="update" dev="ggregory" due-to="Dependabot">Bump h2 from 2.1.214 to 2.2.220 #333.</action>
5355
<action type="update" dev="ggregory" due-to="Gary Gregory">Bump commons-lang3 from 3.12.0 to 3.13.0.</action>
5456
</release>

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

Lines changed: 166 additions & 16 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,13 +571,36 @@ public Builder setHeader(final String... header) {
521571
}
522572

523573
/**
524-
* Sets the header comments set to the given values. The comments will be printed first with the provided comment marker set by {@link Builder#setCommentMarker(char)}, before the headers. This setting is ignored by the parser.
525-
*
574+
* Sets the header comments to write before the CSV data.
575+
* <p>
576+
* This setting is ignored by the parser.
577+
* </p>
578+
* <p>
579+
* Comments are printed first, before headers.
580+
* </p>
581+
* <p>
582+
* Use {@link #setCommentMarker(char)} or {@link #setCommentMarker(Character)} to set the comment marker written at the start of
583+
* each comment line.
584+
* </p>
585+
* <p>
586+
* If the comment marker is not set, then the header comments are ignored.
587+
* </p>
588+
* <p>
589+
* For example:
590+
* </p>
591+
* <pre>
592+
* builder.setCommentMarker('#')
593+
* .setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0));
594+
* </pre>
595+
* <p>
596+
* writes:
597+
* </p>
526598
* <pre>
527-
* builder.setHeaderComments(&quot;Generated by Apache Commons CSV.&quot;, Instant.now());
599+
* # Generated by Apache Commons CSV.
600+
* # 1970-01-01T00:00:00Z
528601
* </pre>
529602
*
530-
* @param headerComments the headerComments which will be printed by the Printer before the actual CSV data.
603+
* @param headerComments the headerComments which will be printed by the Printer before the CSV data.
531604
* @return This instance.
532605
*/
533606
public Builder setHeaderComments(final Object... headerComments) {
@@ -536,13 +609,36 @@ public Builder setHeaderComments(final Object... headerComments) {
536609
}
537610

538611
/**
539-
* Sets the header comments set to the given values. The comments will be printed first with the provided comment marker set by {@link Builder#setCommentMarker(char)}, before the headers. This setting is ignored by the parser.
540-
*
612+
* Sets the header comments to write before the CSV data.
613+
* <p>
614+
* This setting is ignored by the parser.
615+
* </p>
616+
* <p>
617+
* Comments are printed first, before headers.
618+
* </p>
619+
* <p>
620+
* Use {@link #setCommentMarker(char)} or {@link #setCommentMarker(Character)} to set the comment marker written at the start of
621+
* each comment line.
622+
* </p>
623+
* <p>
624+
* If the comment marker is not set, then the header comments are ignored.
625+
* </p>
626+
* <p>
627+
* For example:
628+
* </p>
629+
* <pre>
630+
* builder.setCommentMarker('#')
631+
* .setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0).toString());
632+
* </pre>
633+
* <p>
634+
* writes:
635+
* </p>
541636
* <pre>
542-
* Builder.setHeaderComments(&quot;Generated by Apache Commons CSV.&quot;, Instant.now());
637+
* # Generated by Apache Commons CSV.
638+
* # 1970-01-01T00:00:00Z
543639
* </pre>
544640
*
545-
* @param headerComments the headerComments which will be printed by the Printer before the actual CSV data.
641+
* @param headerComments the headerComments which will be printed by the Printer before the CSV data.
546642
* @return This instance.
547643
*/
548644
public Builder setHeaderComments(final String... headerComments) {
@@ -1523,7 +1619,34 @@ public boolean getAutoFlush() {
15231619
}
15241620

15251621
/**
1526-
* 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>
1633+
* <p>
1634+
* If the comment marker is not set, then the header comments are ignored.
1635+
* </p>
1636+
* <p>
1637+
* For example:
1638+
* </p>
1639+
* <pre>
1640+
* builder.setCommentMarker('#')
1641+
* .setHeaderComments("Generated by Apache Commons CSV", Instant.ofEpochMilli(0));
1642+
* </pre>
1643+
* <p>
1644+
* writes:
1645+
* </p>
1646+
* <pre>
1647+
* # Generated by Apache Commons CSV.
1648+
* # 1970-01-01T00:00:00Z
1649+
* </pre>
15271650
*
15281651
* @return the comment start marker, may be {@code null}
15291652
*/
@@ -1581,7 +1704,34 @@ public String[] getHeader() {
15811704
}
15821705

15831706
/**
1584-
* 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>
15851735
*
15861736
* @return a copy of the header comment array; {@code null} if disabled.
15871737
*/

0 commit comments

Comments
 (0)