docs(json): complete documentation (#4058)

* chore(json): complete documentation * fmt * Capital * Add options and clearer format * tweaks --------- Co-authored-by: Yoshiya Hinosawa <stibium121@gmail.com> Co-authored-by: Asher Gomez <ashersaupingomez@gmail.com>
denoland · Jan 5, 2024 · 524abaf · 524abaf
1 parent 5351ef3
commit 524abaf
Show file tree

Hide file tree

Showing 4 changed files with 41 additions and 20 deletions.
diff --git a/json/common.ts b/json/common.ts
@@ -10,10 +10,21 @@ export type JsonValue =
   | boolean
   | null;
 
-/** Optional object interface for `JSONParseStream` and `ConcatenatedJsonParseStream`. */
+/**
+ * Options for {@linkcode JsonParseStream} and
+ * {@linkcode ConcatenatedJsonParseStream}.
+ */
 export interface ParseStreamOptions {
-  /** Controls the buffer of the TransformStream used internally. Check https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream. */
+  /**
+   * Controls the buffer of the {@linkcode TransformStream} used internally.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream#writablestrategy}
+   */
   readonly writableStrategy?: QueuingStrategy<string>;
-  /** Controls the buffer of the TransformStream used internally. Check https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream. */
+  /**
+   * Controls the buffer of the {@linkcode TransformStream} used internally.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream#readablestrategy}
+   */
   readonly readableStrategy?: QueuingStrategy<JsonValue>;
 }
diff --git a/json/concatenated_json_parse_stream.ts b/json/concatenated_json_parse_stream.ts
@@ -13,7 +13,7 @@ const primitives = new Map(
 );
 
 /**
- * Stream to parse [Concatenated JSON](https://en.wikipedia.org/wiki/JSON_streaming#Concatenated_JSON).
+ * Stream to parse {@link https://en.wikipedia.org/wiki/JSON_streaming#Concatenated_JSON|Concatenated JSON}.
  *
  * @example
  * ```ts
@@ -33,13 +33,12 @@ const primitives = new Map(
  */
 export class ConcatenatedJsonParseStream
   implements TransformStream<string, JsonValue> {
+  /** A writable stream of byte data. */
   readonly writable: WritableStream<string>;
+  /** A readable stream of byte data. */
   readonly readable: ReadableStream<JsonValue>;
-  /**
-   * @param options
-   * @param options.writableStrategy Controls the buffer of the TransformStream used internally. Check https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream.
-   * @param options.readableStrategy Controls the buffer of the TransformStream used internally. Check https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream.
-   */
+
+  /** Constructs a new instance. */
   constructor({ writableStrategy, readableStrategy }: ParseStreamOptions = {}) {
     const { writable, readable } = toTransformStream(
       this.#concatenatedJSONIterator,

diff --git a/json/json_parse_stream.ts b/json/json_parse_stream.ts
@@ -56,11 +56,7 @@ function isBrankString(str: string) {
  * ```
  */
 export class JsonParseStream extends TransformStream<string, JsonValue> {
-  /**
-   * @param options
-   * @param options.writableStrategy Controls the buffer of the TransformStream used internally. Check https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream.
-   * @param options.readableStrategy Controls the buffer of the TransformStream used internally. Check https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream.
-   */
+  /** Constructs new instance. */
   constructor({ writableStrategy, readableStrategy }: ParseStreamOptions = {}) {
     super(
       {

diff --git a/json/json_stringify_stream.ts b/json/json_stringify_stream.ts
@@ -1,28 +1,42 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-/** Optional object interface for `JsonStringifyStream`. */
+/** Options for {@linkcode JsonStringifyStream}. */
 export interface StringifyStreamOptions {
-  /** Prefix to be added after stringify.
+  /**
+   * Prefix to be added after stringify.
    *
    * @default {""}
    */
   readonly prefix?: string;
-  /** Suffix to be added after stringify.
+  /**
+   * Suffix to be added after stringify.
    *
    * @default {"\n"}
    */
   readonly suffix?: string;
-  /** Controls the buffer of the TransformStream used internally. Check https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream. */
+  /**
+   * Controls the buffer of the {@linkcode TransformStream} used internally.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream#writablestrategy}
+   */
   readonly writableStrategy?: QueuingStrategy<unknown>;
-  /** Controls the buffer of the TransformStream used internally. Check https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream. */
+  /**
+   * Controls the buffer of the {@linkcode TransformStream} used internally.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TransformStream/TransformStream#readablestrategy}
+   */
   readonly readableStrategy?: QueuingStrategy<string>;
 }
 
 /**
  * Convert each chunk to JSON string.
  *
- * This can be used to stringify [JSON lines](https://jsonlines.org/), [NDJSON](http://ndjson.org/), [JSON Text Sequences](https://datatracker.ietf.org/doc/html/rfc7464), and [Concatenated JSON](https://en.wikipedia.org/wiki/JSON_streaming#Concatenated_JSON).
+ * This can be used to stringify {@link https://jsonlines.org/|JSON lines},
+ * {@link https://ndjson.org/|NDJSON},
+ * {@link https://datatracker.ietf.org/doc/html/rfc7464|JSON Text Sequences},
+ * and {@link https://en.wikipedia.org/wiki/JSON_streaming#Concatenated_JSON|Concatenated JSON}.
+ *
  * You can optionally specify a prefix and suffix for each chunk. The default prefix is "" and the default suffix is "\n".
  *
  * @example
@@ -82,6 +96,7 @@ export interface StringifyStreamOptions {
  * ```
  */
 export class JsonStringifyStream extends TransformStream<unknown, string> {
+  /** Constructs new instance. */
   constructor({
     prefix = "",
     suffix = "\n",