add comment example

docs/src/content/docs/guides/Examples/handle-comments.mdx

@@ -0,0 +1,54 @@
+---
+title: Handle comments
+---
+
+import {Code} from '@astrojs/starlight/components';
+import readSourceCode from '../../../../../../example/src/main/java/example/ExampleCsvReaderWithComments.java?raw';
+import writeSourceCode from '../../../../../../example/src/main/java/example/ExampleCsvWriterWithComments.java?raw';
+
+Although comments are not part of the CSV standard (per [RFC 4180](https://datatracker.ietf.org/doc/html/rfc4180)),
+many applications make use of comments in CSV files to provide additional information or to add context to the data.
+
+:::note
+Most commonly, comments in CSV files are denoted by a `#` (hash) character at the beginning of a line. This is also
+the default comment character used by FastCSV when reading or writing CSV files, but you can change that by
+calling the `commentCharacter(char)` method on the `CsvReaderBuilder` or `CsvWriterBuilder` class.
+:::
+
+A simple example of a CSV file with comments is shown below:
+
+```
+#This is a comment
+field 1,field 2,field 3
+```
+
+A more complex example of a CSV file with comments is shown below.
+It shows how comments could be misinterpreted as part of a field if not handled correctly:
+
+```
+#This is a comment
+field 1,"field 2 with a # character","field 3
+#This is not a comment, but part of the third field that spans multiple lines"
+```
+
+## Reading CSV files with comments
+
+When reading comments, FastCSV provides flexibility in how comments are handled.
+You may ignore comments entirely by treating them as part of the data, skip them, or read and interpret them as comments.
+More information about the `CommentStrategy` enum can be found in the corresponding
+[JavaDoc](https://javadoc.io/doc/de.siegmar/fastcsv/latest/de.siegmar.fastcsv/de/siegmar/fastcsv/reader/CommentStrategy.html).
+
+By default, FastCSV treats comments as part of the data to ensure that no data is lost and to maintain
+maximum compatibility with the RFC 4180 standard.
+
+<Code code={readSourceCode} title="ExampleCsvReaderWithComments.java" lang="java" />
+
+## Writing CSV files with comments
+
+Writing comments to a CSV file is straightforward, as FastCSV takes care of any necessary escaping or line breaks.
+
+:::caution
+Be aware that comments are not part of the CSV standard and may not be supported by all applications that read CSV files.
+:::
+
+<Code code={writeSourceCode} title="ExampleCsvWriterWithComments.java" lang="java" />

example/src/main/java/example/ExampleCsvWriterWithComments.java

@@ -12,10 +12,8 @@ public class ExampleCsvWriterWithComments {
  public static void main(final String[] args) {
  final StringWriter sw = new StringWriter();
  CsvWriter.builder().build(sw)
- .writeComment("A comment can be placed")
- .writeRecord("header1", "header2")
- .writeComment("anywhere")
- .writeRecord("value1", "value2")
+ .writeComment("A comment can be placed\nanywhere")
+ .writeRecord("field 1", "field 2", "field 3\n#with a line break")
  .writeComment("in the CSV file");
 
  System.out.println(sw);