Buddhi De Silva created CSV-308:
-----------------------------------
Summary: 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
Attachments: log_optimization.patch
Hi Team.
I am new to the Apache contribution and I would like to contribute.
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)
