docs: add JSDoc to csv and json modules (#3269)

denoland · Mar 24, 2023 · b2d7191 · b2d7191
1 parent a7051dd
commit b2d7191
Show file tree

Hide file tree

Showing 5 changed files with 111 additions and 5 deletions.
diff --git a/csv/_io.ts b/csv/_io.ts
@@ -12,11 +12,17 @@ export interface ReadOptions {
    */
   separator?: string;
   /** Character to start a comment.
+   *
+   * Lines beginning with the comment character without preceding whitespace
+   * are ignored. With leading whitespace the comment character becomes part of
+   * the field, even you provide `trimLeadingSpace: true`.
    *
    * @default {"#"}
    */
   comment?: string;
   /** Flag to trim the leading space of the value.
+   *
+   * This is done even if the field delimiter, `separator`, is white space.
    *
    * @default {false}
    */
@@ -29,8 +35,15 @@ export interface ReadOptions {
    */
   lazyQuotes?: boolean;
   /**
-   * Enabling the check of fields for each row. If == 0, first row is used as
-   * referral for the number of fields.
+   * Enabling checking number of expected fields for each row.
+   *
+   * If positive, each record is required to have the given number of fields.
+   * If == 0, it will be set to the number of fields in the first row, so that
+   * future rows must have the same field count.
+   * If negative, no check is made and records may have a variable number of
+   * fields.
+   *
+   * If the wrong number of fields is in a row, a `ParseError` is thrown.
    */
   fieldsPerRecord?: number;
 }

diff --git a/csv/mod.ts b/csv/mod.ts
@@ -1,6 +1,68 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
+/** Reads and writes comma-separated values (CSV) files.
+ *
+ * There are many kinds of CSV files; this module supports the format described
+ * in [RFC 4180](https://www.rfc-editor.org/rfc/rfc4180.html).
+ *
+ * A csv file contains zero or more records of one or more fields per record.
+ * Each record is separated by the newline character. The final record may
+ * optionally be followed by a newline character.
+ *
+ * ```csv
+ * field1,field2,field3
+ * ```
+ *
+ * White space is considered part of a field.
+ *
+ * Carriage returns before newline characters are silently removed.
+ *
+ * Blank lines are ignored. A line with only whitespace characters (excluding
+ * the ending newline character) is not considered a blank line.
+ *
+ * Fields which start and stop with the quote character " are called
+ * quoted-fields. The beginning and ending quote are not part of the field.
+ *
+ * The source:
+ *
+ * ```csv
+ * normal string,"quoted-field"
+ * ```
+ *
+ * results in the fields
+ *
+ * ```ts
+ * [`normal string`, `quoted-field`]
+ * ```
+ *
+ * Within a quoted-field a quote character followed by a second quote character is considered a single quote.
+ *
+ * ```csv
+ * "the ""word"" is true","a ""quoted-field"""
+ * ```
+ *
+ * results in
+ *
+ * [`the "word" is true`, `a "quoted-field"`]
+ *
+ * Newlines and commas may be included in a quoted-field
+ *
+ * ```csv
+ * "Multi-line
+ * field","comma is ,"
+ * ```
+ *
+ * results in
+ *
+ * ```ts
+ * [`Multi-line
+ * field`, `comma is ,`]
+ * ```
+ *
+ * @module
+ */
+
 export * from "./stringify.ts";
 export * from "./parse.ts";
 export * from "./stream.ts";
diff --git a/csv/stream.ts b/csv/stream.ts
@@ -6,14 +6,21 @@ import {
   defaultReadOptions,
   type LineReader,
   parseRecord,
+  type ReadOptions,
   type RowType,
 } from "../csv/_io.ts";
 import { TextDelimiterStream } from "../streams/text_delimiter_stream.ts";
 
-export interface CsvStreamOptions {
-  separator?: string;
-  comment?: string;
+export interface CsvStreamOptions extends ReadOptions {
+  /**
+   * If you provide `skipFirstRow: true` and `columns`, the first line will be
+   * skipped.
+   * If you provide `skipFirstRow: true` but not `columns`, the first line will
+   * be skipped and used as header definitions.
+   */
   skipFirstRow?: boolean;
+
+  /** List of names used for header definition. */
   columns?: string[];
 }
 
@@ -48,6 +55,22 @@ function stripLastCR(s: string): string {
   return s.endsWith("\r") ? s.slice(0, -1) : s;
 }
 
+/**
+ * Read data from a CSV-encoded stream or file.
+ * Provides an auto/custom mapper for columns.
+ *
+ * A `CsvStream` expects input conforming to
+ * [RFC 4180](https://rfc-editor.org/rfc/rfc4180.html).
+ *
+ * @example
+ * ```ts
+ * import { CsvStream } from "https://deno.land/std@$STD_VERSION/csv/stream.ts";
+ * const res = await fetch("https://example.com/data.csv");
+ * const parts = res.body!
+ *   .pipeThrough(new TextDecoderStream())
+ *   .pipeThrough(new CsvStream());
+ * ```
+ */
 export class CsvStream<T extends CsvStreamOptions>
   implements TransformStream<string, RowType<CsvStreamOptions, T>> {
   readonly #readable: ReadableStream<

diff --git a/csv/stringify.ts b/csv/stringify.ts
@@ -214,6 +214,8 @@ function getValuesFromItem(
 }
 
 /**
+ * Write data using CSV encoding.
+ *
  * @param data The source data to stringify. It's an array of items which are
  * plain objects or arrays.
  *

diff --git a/json/mod.ts b/json/mod.ts
@@ -1,4 +1,10 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+
+/** Utilities for parsing streaming JSON data.
+ *
+ * @module
+ */
+
 export * from "./concatenated_json_parse_stream.ts";
 export * from "./common.ts";
 export * from "./json_parse_stream.ts";
-Original file line number
+Diff line change
@@ Expand Up / @@ -214,6 +214,8 @@ function getValuesFromItem( @@
     }
     /**
+     * Write data using CSV encoding.
+     *
      * @param data The source data to stringify. It's an array of items which are
      * plain objects or arrays.
      *
@@ Expand Down @@