Apr 18 2026 Patch (#306)

* Fix issue 195

* Remove useless comments

Author: vincentlaucsb

AGENTS.md

@@ -73,9 +73,7 @@ ThreadSafeDeque<CSVRow>
 3. **Don't use uniform values:** Each column needs distinct values to detect corruption.
 4. **Don't ignore async:** Worker thread means exceptions must use `exception_ptr`.
 5. **Don't change one constructor:** Likely affects both mmap and stream paths.
-6. **Don't delete or simplify comments** unless they are trivially obvious (e.g. `// increment i`) or factually incorrect. Comments in this codebase frequently encode concurrency invariants, non-obvious design decisions, and hard-won bug context that cannot be recovered from the code alone.
 7. **Compatibility macros defined in `common.hpp` MUST be referenced only after including `common.hpp`.** Any macro (such as `CSV_HAS_CXX20`) that is defined in `common.hpp` must not be used or checked before `#include "common.hpp"` appears in the file. This ensures feature detection and conditional compilation work as intended across all supported compilers and build modes.
-7. **Don't reference internal functions in public API comments.** Public API docs should describe user-visible behavior and contracts; internal helper/function details belong in internal docs.
 8. **`CSVReader` is non-copyable and move-enabled.** Prefer explicit ownership transfer (`std::move`) or `std::unique_ptr<CSVReader>` when sharing/handing off parser ownership across APIs.
 9. **Prefer trailing underscore for private members** (for example `source_`, `leftover_`). When you touch code with mixed private-member naming styles, normalize the edited region toward trailing underscores instead of introducing more leading-underscore or unsuffixed names.
 10. **Prefer user-friendly API constraints.** Do not narrow template constraints unless required for correctness, safety, or a measured performance win. If an implementation already handles common standard-library containers/ranges correctly, keep those inputs accepted instead of over-constraining APIs for aesthetic purity.
@@ -86,3 +84,9 @@ ThreadSafeDeque<CSVRow>
 15. **If a build fix appears to require more than ~3 files or ~60 changed lines, pause and confirm scope first.** Provide a short justification before expanding further.
 
 See `tests/AGENTS.md` for test strategy, checklist, and conventions.
+
+### Rules for Comments
+1. **Always update or remove incorrect comments.**
+2. **Don't reference internal functions in public API comments.** Public API docs should describe user-visible behavior and contracts; internal helper/function details belong in internal docs.
+3. **Avoid meaningless @param and @return descriptions.** Do not add comments that could trivially be inferred by the function's name or other existing comments. When editing a function, remove any @param/@return descriptions that merely restate the function name or signature.
+4. **Don't delete or simplify comments** unless allowed by other rules in this section. Comments in this codebase frequently encode concurrency invariants, non-obvious design decisions, and hard-won bug context that cannot be recovered from the code alone.

ARCHITECTURE.md

@@ -15,7 +15,9 @@ Operational/testing guidance:
 Notes:
 - Internal architecture content lives under include/internal to stay close to implementation.
 - Queue synchronization details are maintained only in THREADSAFE_DEQUE_DESIGN.md to avoid duplication.
+- Always update or remove incorrect comments.
 - Public API comments should remain user-facing and avoid references to internal helper/function details.
+- When editing a function, remove `@param` and `@return` descriptions that merely restate the function name or signature.
 - Private member naming should prefer trailing underscores; when editing mixed-style code, normalize the touched region toward that convention.
 - Compatibility macros defined in `common.hpp` must only be referenced after including `common.hpp`. See AGENTS.md and CLAUDE.md for details.
 - API constraints should be user-friendly: do not over-constrain templates unless needed for correctness, safety, or a measured performance win.

CLAUDE.md

@@ -35,9 +35,11 @@
 - Use distinct column values to detect field corruption
 - Exceptions from worker thread need `exception_ptr`
 - Changes to one constructor likely affect both paths
+- **Always update or remove incorrect comments**
 - **Do not delete or simplify comments** unless trivially obvious or factually wrong — comments encode concurrency invariants and bug history
 - **Compatibility macros defined in `common.hpp` MUST be referenced only after including `common.hpp`.** Any macro (such as `CSV_HAS_CXX20`) that is defined in `common.hpp` must not be used or checked before `#include "common.hpp"` appears in the file. This ensures feature detection and conditional compilation work as intended across all supported compilers and build modes.
 - **Do not reference internal functions in public API comments** — public API docs should remain user-facing; internal details belong in internal docs
+- **Remove meaningless `@param` and `@return` docs when editing a function** — if they merely restate the name or signature, delete them instead of preserving noise
 - **`CSVReader` is non-copyable and move-enabled** — prefer explicit ownership transfer (`std::move`) or `std::unique_ptr<CSVReader>` when handing off parser ownership
 - **Prefer trailing underscore for private members** — when touching mixed-style code, normalize the edited region toward names like `source_` and `leftover_`
 - **Prefer user-friendly API constraints** — do not narrow template constraints unless required for correctness, safety, or a measured performance win; if common containers/ranges already work, keep them accepted

include/internal/basic_csv_parser.cpp

@@ -140,7 +140,7 @@ namespace csv {
             field_length_ = 0;
         }
 
-        /** @return The number of characters parsed that belong to complete rows */
+        /** Parse the current chunk and return the number of bytes belonging to complete rows. */
         CSV_INLINE size_t IBasicCSVParser::parse()
         {
             using internals::ParseFlags;

include/internal/basic_csv_parser.hpp

@@ -178,10 +178,7 @@ namespace csv {
             /** Whether or not source needs to be read in chunks */
             CONSTEXPR bool no_chunk() const { return this->source_size_ < CSV_CHUNK_SIZE_DEFAULT; }
 
-            /** Parse the current chunk of data *
-             *
-             *  @returns How many character were read that are part of complete rows
-             */
+            /** Parse the current chunk of data and return the completed-row prefix length. */
             size_t parse();
 
             /** Create a new RawCSVDataPtr for a new chunk of data */

include/internal/csv_format.cpp

@@ -43,6 +43,7 @@ namespace csv {
         if (row < 0) this->variable_column_policy = VariableColumnPolicy::KEEP;
 
         this->header = row;
+        this->header_explicitly_set_ = true;
         this->col_names = {};
         return *this;
     }

include/internal/csv_format.hpp

@@ -53,14 +53,12 @@ namespace csv {
         /** Sets a list of potential delimiters
          *  
          *  @throws `std::runtime_error` thrown if trim, quote, or possible delimiting characters overlap
-         *  @param[in] delim An array of possible delimiters to try parsing the CSV with
          */
         CSVFormat& delimiter(const std::vector<char> & delim);
 
         /** Sets the whitespace characters to be trimmed
          *
          *  @throws `std::runtime_error` thrown if trim, quote, or possible delimiting characters overlap
-         *  @param[in] ws An array of whitespace characters that should be trimmed
          */
         CSVFormat& trim(const std::vector<char> & ws);
 
@@ -156,8 +154,11 @@ namespace csv {
         CSV_INLINE static CSVFormat guess_csv() {
             CSVFormat format;
             format.delimiter({ ',', '|', '\t', ';', '^' })
-                .quote('"')
-                .header_row(0);
+                .quote('"');
+            // Assign header directly rather than via header_row() so that
+            // header_explicitly_set_ remains false — the guesser must be free
+            // to detect the real header row at construction time.
+            format.header = 0;
 
             return format;
         }
@@ -182,6 +183,9 @@ namespace csv {
         /**< Row number with columns (ignored if col_names is non-empty) */
         int header = 0;
 
+        /**< True if the user explicitly called header_row() or no_header() */
+        bool header_explicitly_set_ = false;
+
         /**< Whether or not to use quoting */
         bool no_quote = false;
 

include/internal/csv_reader.cpp

@@ -19,12 +19,7 @@ namespace csv {
             return ret.str();
         }
 
-        /** Return a CSV's column names
-         *
-         *  @param[in] filename  Path to CSV file
-         *  @param[in] format    Format of the CSV file
-         *
-         */
+        /** Return the selected header row from a parsed head buffer. */
         CSV_INLINE std::vector<std::string> _get_col_names(csv::string_view head, CSVFormat format) {
             // Parse the CSV
             auto trim_chars = format.get_trim_chars();
@@ -129,12 +124,7 @@ namespace csv {
         }
     }
 
-    /** Return a CSV's column names
-     *
-     *  @param[in] filename  Path to CSV file
-     *  @param[in] format    Format of the CSV file
-     *
-     */
+    /** Return a CSV's column names. */
     CSV_INLINE std::vector<std::string> get_col_names(csv::string_view filename, CSVFormat format) {
         auto head = internals::get_csv_head(filename);
 
@@ -158,9 +148,6 @@ namespace csv {
      *  **Details:** Reads the first block of a CSV file synchronously to get information
      *               such as column names and delimiting character.
      *
-     *  @param[in] filename  Path to CSV file
-     *  @param[in] format    Format of the CSV file
-     *
      *  \snippet tests/test_read_csv.cpp CSVField Example
      *
      */
@@ -184,10 +171,11 @@ namespace csv {
         if (format.guess_delim()) {
             auto guess_result = internals::_guess_format(head, format.possible_delimiters);
             format.delimiter(guess_result.delim);
-            // Only override header if user hasn't explicitly called no_header()
-            // Note: column_names() also sets header=-1, but it populates col_names,
-            // so we can distinguish: no_header() means header=-1 && col_names.empty()
-            if (format.header != -1 || !format.col_names.empty()) {
+            // Only override header if the user hasn't explicitly set one via
+            // header_row() or no_header(). column_names() sets col_names but
+            // does not set header_explicitly_set_, so the guesser can still
+            // determine where the data rows begin in that case.
+            if (!format.header_explicitly_set_) {
                 format.header = guess_result.header_row;
             }
 
@@ -246,9 +234,7 @@ namespace csv {
         }
     }
 
-    /**
-     *  @param[in] names Column names
-     */
+    /** Install the active column names for this reader. */
     CSV_INLINE void CSVReader::set_col_names(const std::vector<std::string>& names)
     {
         this->col_names->set_policy(this->_format.get_column_name_policy());
@@ -262,8 +248,6 @@ namespace csv {
      * @note This method is meant to be run on its own thread. Only one `read_csv()` thread
      *       should be active at a time.
      *
-     * @param[in] bytes Number of bytes to read.
-     *
      * @see CSVReader::read_csv_worker
      * @see CSVReader::read_row()
      */
@@ -309,7 +293,6 @@ namespace csv {
     *  - Reads chunks of data that are csv::internals::CSV_CHUNK_SIZE_DEFAULT bytes large at a time
      *  - For performance details, read the documentation for CSVRow and CSVField.
      *
-     * @param[out] row The variable where the parsed row will be stored
      * @see CSVRow, CSVField
      *
      * **Example:**

include/internal/csv_reader.hpp

@@ -47,10 +47,6 @@ namespace csv {
         const CSVFormat format = CSVFormat::guess_csv());
 
     /** @brief Guess the delimiter and header row of a CSV file
-     *
-     *  @param[in] filename  Path to CSV file
-     *  @param[in] delims    Candidate delimiters to test
-     *  @return CSVGuessResult containing the detected delimiter and header row index
      *
      *  **Heuristic:** For each candidate delimiter, calculate a score based on
      *  the most common row length (mode). The delimiter with the highest score wins.
@@ -107,28 +103,23 @@ namespace csv {
          * streaming large CSV files that may exceed available RAM (e.g., 50+ GB files).
          * 
          * @par CRITICAL DESIGN CONSTRAINT:
-         * - The underlying RawCSVData chunks are automatically freed as the iterator advances
-         * - Only the CURRENT row's data is kept alive (via CSVRow's RawCSVDataPtr member)
-         * - Previous chunks are freed to allow unlimited file sizes with bounded memory
+         * - Storage for previously consumed positions may be released as the iterator advances
+         * - Only the current position is guaranteed to remain valid without copying
+         * - This bounded-memory behavior is what allows very large CSV files to stream safely
          * 
          * @par WHY FORWARD ITERATOR IS NOT POSSIBLE:
          * - ForwardIterator requires multi-pass guarantees (can hold multiple valid positions)
-         * - Supporting this would require caching ALL RawCSVDataPtr chunks in the iterator
+         * - Supporting this would require retaining all parsed row storage in memory
          * - This defeats the streaming purpose: a 50 GB CSV would require 50+ GB of RAM
          * - The entire library design depends on automatic chunk cleanup for memory efficiency
          * 
          * @par IMPLICATIONS FOR ALGORITHM USE:
          * - Algorithms requiring ForwardIterator (std::max_element, std::sort, etc.) may
-         *   appear to work in tests with small files, but will cause heap-use-after-free
-         *   when the algorithm tries to access iterators pointing to freed chunks
+         *   appear to work in tests with small files, but are not safe on this iterator
+         *   once earlier positions have been released during streaming
          * - CORRECT approach: Copy rows to std::vector first, then use algorithms
          * - Example: auto rows = std::vector<CSVRow>(reader.begin(), reader.end());
          *            auto max_row = std::max_element(rows.begin(), rows.end(), ...);
-         * 
-         * @par FOR AI AGENTS AND MAINTAINERS:
-         * If you encounter heap-use-after-free with ForwardIterator algorithms, the solution
-         * is NOT to cache all RawCSVDataPtr chunks - this violates the fundamental streaming
-         * architecture. Instead, document the limitation or provide vector-based workarounds.
          */
         class iterator {
         public:

include/internal/csv_reader_iterator.cpp

@@ -14,8 +14,8 @@ namespace csv {
         return CSVReader::iterator(this, std::move(row));
     }
 
-    /** A placeholder for the imaginary past the end row in a CSV.
-     *  Attempting to deference this will lead to bad things.
+    /** A placeholder for the imaginary past-the-end row in a CSV.
+     *  Attempting to dereference this iterator is undefined.
      */
     CSV_INLINE CSV_CONST CSVReader::iterator CSVReader::end() const noexcept {
         return CSVReader::iterator();