fix review comments

Author: HuaHuaY

cpp/src/arrow/csv/options.h

@@ -210,6 +210,9 @@ struct ARROW_EXPORT WriteOptions {
   QuotingStyle quoting_style = QuotingStyle::Needed;
 
   /// \brief Quoting style of header
+  ///
+  /// Note that `QuotingStyle::Needed` and `QuotingStyle::AllValid` have the same
+  /// effect of quoting all column names.
   QuotingStyle quoting_header = QuotingStyle::Needed;
 
   /// Create write options with default values

cpp/src/arrow/csv/writer.cc

@@ -105,7 +105,7 @@ int64_t CountQuotes(std::string_view s) {
 
 // Matching quote pair character length.
 constexpr int64_t kQuoteCount = 2;
-// Matching delimiter character length.
+// Delimiter character length.
 constexpr int64_t kDelimiterCount = 1;
 
 // Interface for generating CSV data per column.
@@ -177,6 +177,8 @@ char* Escape(std::string_view s, char* out) {
   return out;
 }
 
+// Return the index of the first structural char in the input. A structural char
+// is a character that needs quoting and/or escaping.
 int64_t StopAtStructuralChar(const uint8_t* data, const int64_t buffer_size,
                              const char delimiter) {
   int64_t offset = 0;
@@ -634,11 +636,11 @@ class CSVWriterImpl : public ipc::RecordBatchWriter {
           memcpy(next, col_name.data(), col_name.size());
           next += col_name.size();
           break;
-        // The behavior of the Needed quoting_style in CSV data depends on the data type.
-        // And it is always quoted when the data type is binary. To avoid semantic
-        // differences, the behavior of Need and AllValid should be consistent.
         case QuotingStyle::Needed:
         case QuotingStyle::AllValid:
+          // QuotingStyle::Needed is defined as always quoting string/binary data,
+          // regardless of whether it contains structural chars.
+          // We use consistent semantics for header names, which are strings.
           *next++ = '"';
           next = Escape(schema_->field(col)->name(), next);
           *next++ = '"';

cpp/src/arrow/csv/writer_test.cc

@@ -93,9 +93,10 @@ std::vector<WriterTestParams> GenerateTestCases() {
   auto dummy_schema = schema({field("a", uint8())});
   std::string dummy_batch_data = R"([{"a": null}])";
 
-  auto header_without_structral_charaters =
+  auto header_without_structural_charaters =
       schema({field("a ", uint64()), field("b", int32())});
-  std::string expected_header_without_structral_charaters = std::string(R"(a ,b)") + "\n";
+  std::string expected_header_without_structural_charaters =
+      std::string(R"(a ,b)") + "\n";
   auto expected_status_no_quotes_with_structural_in_header = [](const char* header) {
     return Status::Invalid(
         "CSV header may not contain structural characters if quoting "
@@ -292,12 +293,12 @@ std::vector<WriterTestParams> GenerateTestCases() {
        DefaultTestOptions(/*include_header=*/false, /*null_string=*/"",
                           QuotingStyle::Needed, /*eol=*/";", /*delimiter=*/';'),
        /*expected_output*/ "", expected_status_illegal_delimiter(';')},
-      {header_without_structral_charaters, "[]",
+      {header_without_structural_charaters, "[]",
        DefaultTestOptions(/*include_header=*/true, /*null_string=*/"",
                           QuotingStyle::Needed, /*eol=*/"\n",
                           /*delimiter=*/',', /*batch_size=*/5,
                           /*quoting_header=*/QuotingStyle::None),
-       expected_header_without_structral_charaters},
+       expected_header_without_structural_charaters},
       {abc_schema, "[]",
        DefaultTestOptions(/*include_header=*/true, /*null_string=*/"",
                           QuotingStyle::Needed, /*eol=*/"\n",