[jira] [Resolved] (CSV-308) Possible Javadoc optimization for method 'setHeaderComments'

["Gary D. Gregory (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/CSV-308?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Gary D. Gregory resolved CSV-308.
---------------------------------
    Fix Version/s: 1.10.1
       Resolution: Fixed

> 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
>             Fix For: 1.10.1
>
>         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(&quot;Generated by Apache Commons CSV.&quot;, 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)