Details
-
Improvement
-
Status: Closed
-
Minor
-
Resolution: Fixed
-
1.10.0
-
Library version used: org.apache.commons:commons-csv:1.10.0
Testing Env.: Windows
Description
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.
CSVFormat csvFormat = CSVFormat.DEFAULT.builder() .setHeader(headerList.toArray(new String[0])) .setDelimiter(",") .setHeaderComments("Sample header comment one", "Sample header comment two") .setCommentMarker('-') .build();
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()'.
/**
* 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.
*/
Following is the modified comment line I am proposing...
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.
Appreciate your feedback on this.
Patch file is attached.
PR link: https://github.com/apache/commons-csv/pull/344
