From 47dc4c29b0bc231de0614cab4630dcfe26c2e07d Mon Sep 17 00:00:00 2001
From: Oliver Siegmar <oliver@siegmar.de>
Date: Mon, 26 Aug 2024 17:50:09 +0200
Subject: [PATCH] add comment example

---
 .../docs/guides/Examples/handle-comments.mdx  | 54 +++++++++++++++++++
 .../example/ExampleCsvWriterWithComments.java |  6 +--
 2 files changed, 56 insertions(+), 4 deletions(-)
 create mode 100644 docs/src/content/docs/guides/Examples/handle-comments.mdx

diff --git a/docs/src/content/docs/guides/Examples/handle-comments.mdx b/docs/src/content/docs/guides/Examples/handle-comments.mdx
new file mode 100644
index 00000000..41d79207
--- /dev/null
+++ b/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" />
diff --git a/example/src/main/java/example/ExampleCsvWriterWithComments.java b/example/src/main/java/example/ExampleCsvWriterWithComments.java
index 9db675ff..ea1c59af 100644
--- a/example/src/main/java/example/ExampleCsvWriterWithComments.java
+++ b/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);