[
https://issues.apache.org/jira/browse/CSV-308?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17758544#comment-17758544
]
Buddhi De Silva commented on CSV-308:
-------------------------------------
Hi Team.
I am new to the Apache contribution and I would like to contribute. Please feel
free to change / edit this issue as appropriate.
> Possible Javadoc optimization 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
> Attachments: 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)
