[
https://issues.apache.org/jira/browse/CSV-308?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17760437#comment-17760437
]
Buddhi De Silva commented on CSV-308:
-------------------------------------
Verified in Master branch.
Changes are available.
Closing the issue.
!image-2023-08-30-19-56-12-141.png!
> Javadoc example for method 'setHeaderComments'
> ----------------------------------------------
>
> Key: CSV-308
> URL: https://issues.apache.org/jira/browse/CSV-308
> Project: Commons CSV
> Issue Type: Improvement
> Components: Documentation, Printer
> Affects Versions: 1.10.0
> Environment: Library version used:
> org.apache.commons:commons-csv:1.10.0
> Testing Env.: Windows
> Reporter: Buddhi De Silva
> Priority: Minor
> Labels: documentation, easyfix, pull-request-available
> Fix For: 1.10.1
>
> Attachments: image-2023-08-30-19-56-12-141.png, log_optimization.patch
>
>
> I was trying some samples with Apache CSV library and I have one Javadoc.
> optimization suggestion.
>
> Scenario:
>
> If we want to set a header comment in the CSV when writing a new CSV content,
> we can achieve it by doing following.
> {code:java}
> CSVFormat csvFormat = CSVFormat.DEFAULT.builder()
> .setHeader(headerList.toArray(new String[0]))
> .setDelimiter(",")
> .setHeaderComments("Sample header comment one", "Sample header comment
> two")
> .setCommentMarker('-')
> .build(); {code}
>
> In this case if we do not set the comment marker with method
> 'setCommentMarker('-')' then no any header comment get printed.
> This is obvious but when a developer trying to figure this out (on why
> comments are not getting printed) for the first time, I think it would be
> best if we can specify a simple comment in the Javadoc for the method
> 'setHeaderComments()' to explicitly mention that, it is also required to set
> the comment marker in order to get header comments working properly.
> Or else, we could throw some exception with message similar to: "No any
> comment marker has been set" -> I have tried this but this will cause another
> problem by breaking existing unit test cases.
>
> Currently we have following method comment set for
> 'CSVFormat.setHeaderComments()'.
>
> {code:java}
> /**
> * 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.
> *
> * <pre>
> * Builder.setHeaderComments("Generated by Apache Commons CSV.",
> Instant.now());
> * </pre>
> *
> * @param headerComments the headerComments which will be printed by the
> Printer before the actual CSV data.
> * @return This instance.
> */ {code}
>
> Following is the modified comment line I am proposing...
> {code:java}
> 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. {code}
> Appreciate your feedback on this.
>
> Patch file is attached.
> PR link: [https://github.com/apache/commons-csv/pull/344]
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
