docs(ini): cleanup module documentation (#5566)

ini/mod.ts

@@ -5,54 +5,27 @@
  * {@linkcode parse} and {@linkcode stringify} for handling
  * {@link https://en.wikipedia.org/wiki/INI_file | INI} encoded data, such as the
  * {@link https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s03.html | Desktop Entry specification}.
- * Values are parsed as strings by default to preserve data parity from the original.
- * Customization is possible in the form of reviver/replacer functions like those in `JSON.parse` and `JSON.stringify`.
- * Nested sections, repeated key names within a section, and key/value arrays are not supported,
- * but will be preserved when using {@linkcode IniMap}. Multi-line values are not supported and will throw a syntax error.
- * White space padding and lines starting with '#', ';', or '//' will be treated as comments.
  *
  * ```ts
- * import * as ini from "@std/ini";
+ * import { parse, stringify } from "@std/ini";
  * import { assertEquals } from "@std/assert";
  *
- * const iniFile = `# Example configuration file
- * Global Key=Some data here
- *
+ * const text = `Global Key=Some data here
  * [Section #1]
  * Section Value=42
  * Section Date=1977-05-25`;
  *
- * const parsed = ini.parse(iniFile, {
- *   reviver(key, value, section) {
- *     if (section === "Section #1") {
- *       if (key === "Section Value") return Number(value);
- *       if (key === "Section Date") return new Date(value);
- *     }
- *     return value;
- *   },
- * });
+ * const parsed = parse(text);
  *
- * assertEquals(parsed, {
+ * assertEquals(parse(text), {
  *   "Global Key": "Some data here",
  *   "Section #1": {
- *     "Section Value": 42,
- *     "Section Date": new Date("1977-05-25T00:00:00.000Z"),
+ *     "Section Value": "42",
+ *     "Section Date": "1977-05-25",
  *   },
  * });
  *
- * const text = ini.stringify(parsed, {
- *   replacer(key, value, section) {
- *     if (section === "Section #1" && key === "Section Date") {
- *       return (value as Date).toISOString().split("T")[0];
- *     }
- *     return value;
- *   },
- * });
- *
- * assertEquals(text, `Global Key=Some data here
- * [Section #1]
- * Section Value=42
- * Section Date=1977-05-25`);
+ * assertEquals(stringify(parsed), text);
  * ```
  *
  * @module

ini/parse.ts

@@ -6,12 +6,26 @@ export type { ParseOptions, ReviverFunction };
 
 /** Options for {@linkcode parse}. */
 interface ParseOptions {
-  /** Provide custom parsing of the value in a key/value pair. */
+  /**
+   * Provide custom parsing of the value in a key/value pair. Similar to the
+   * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#reviver | reviver}
+   * function in {@linkcode JSON.parse}.
+   */
   reviver?: ReviverFunction;
 }
 
 /**
- * Parse an INI config string into an object. Provide formatting options to override the default assignment operator.
+ * Parse an INI config string into an object.
+ *
+ * Values are parsed as strings by default to preserve data parity from the
+ * original.
+ *
+ * Nested sections, repeated key names within a section, and key/value arrays
+ * are not supported. White space padding and lines starting with `#`, `;`, or
+ * `//` will be treated as comments.
+ *
+ * @throws {SyntaxError} If the INI string is invalid or if it contains
+ * multi-line values.
  *
  * @example Usage
  * ```ts

ini/stringify.ts

@@ -9,7 +9,12 @@ import {
 
 /** Options for {@linkcode stringify}. */
 export interface StringifyOptions extends FormattingOptions {
-  /** Provide custom string conversion for the value in a key/value pair. */
+  /**
+   * Provide custom string conversion for the value in a key/value pair.
+   * Similar to the
+   * {@linkcode https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#replacer | replacer}
+   * function in {@linkcode JSON.stringify}.
+   */
   replacer?: ReplacerFunction;
 }