doc: adds jsdocs for public methods

kaelzhang · kaelzhang · commit 0b25580a7a6f · 2025-12-11T13:11:20.000+08:00
diff --git a/src/array.js b/src/array.js
@@ -84,13 +84,35 @@ const get_mapped = (map, key) => {
   return mapped
 }
 
+/**
+ * An Array subclass that preserves comments when array operations are performed.
+ *
+ * CommentArray extends the native Array class and automatically handles comment
+ * preservation during array mutations like splice, slice, push, pop, etc.
+ * Comments are stored as symbol properties and are moved/copied appropriately
+ * when the array structure changes.
+ *
+ * @extends Array
+ *
+ * @example
+ * const arr = parse('[1, 2, 3]') // with comments
+ * // arr is a CommentArray instance
+ * arr.splice(1, 1) // Comments are preserved and repositioned correctly
+ */
 class CommentArray extends Array {
   // - deleteCount + items.length
 
   // We should avoid `splice(begin, deleteCount, ...items)`,
   // because `splice(0, undefined)` is not equivalent to `splice(0)`,
   // as well as:
   // - slice
+  /**
+   * Changes the contents of an array by removing or replacing existing elements and/or adding new elements in place.
+   * Comments are automatically preserved and repositioned during the operation.
+   *
+   * @param {...*} args Arguments passed to Array.prototype.splice
+   * @returns {CommentArray} A new CommentArray containing the deleted elements.
+   */
   splice (...args) {
     const {length} = this
     const ret = super.splice(...args)
@@ -136,6 +158,13 @@ class CommentArray extends Array {
     return ret
   }
 
+  /**
+   * Returns a shallow copy of a portion of an array into a new CommentArray object.
+   * Comments are copied to the appropriate positions in the new array.
+   *
+   * @param {...*} args Arguments passed to Array.prototype.slice
+   * @returns {CommentArray} A new CommentArray containing the extracted elements with their comments.
+   */
   slice (...args) {
     const {length} = this
     const array = super.slice(...args)
diff --git a/src/common.js b/src/common.js
@@ -167,7 +167,34 @@ module.exports = {
 
   is_raw_json,
 
-  // TODO: js doc and usage examples
+  /**
+   * Assign properties and comments from source to target object.
+   *
+   * @param {Object} target The target object to assign properties and comments
+   *   to.
+   * @param {Object} source The source object to copy properties and comments
+   *   from.
+   * @param {Array<string|number>} [keys] Optional array of keys to assign. If
+   *   not provided, all keys and non-property comments are assigned. If empty
+   *   array, only non-property comments are assigned.
+   * @returns {Object} The target object with assigned properties and comments.
+   *
+   * @throws {TypeError} If target cannot be converted to object or keys is not
+   *   array or undefined.
+   *
+   * @example
+   * const source = parse('{"a": 1 // comment a, "b": 2 // comment b}')
+   * const target = {}
+   *
+   * // Copy all properties and comments
+   * assign(target, source)
+   *
+   * // Copy only specific properties and their comments
+   * assign(target, source, ['a'])
+   *
+   * // Copy only non-property comments
+   * assign(target, source, [])
+   */
   assign (target, source, keys) {
     if (!isObject(target)) {
       throw new TypeError('Cannot convert undefined or null to object')
@@ -199,7 +226,43 @@ module.exports = {
     return assign(target, source, keys)
   },
 
-  // TODO: js doc and usage examples
+  /**
+   * Move comments from one location to another within objects.
+   *
+   * @param {Object} source The source object containing comments to move.
+   * @param {Object} [target] The target object to move comments to. If not
+   *   provided, defaults to source (move within same object).
+   * @param {Object} from The source comment location.
+   * @param {string} from.kind The kind of comment prefix (e.g., 'before',
+   *   'after', 'before-all', etc.).
+   * @param {string} [from.key] The property key for property-specific comments.
+   *   Omit for non-property comments.
+   * @param {Object} to The target comment location.
+   * @param {string} to.kind The kind of comment prefix (e.g., 'before',
+   *   'after', 'before-all', etc.).
+   * @param {string} [to.key] The property key for property-specific comments.
+   *   Omit for non-property comments.
+   * @param {boolean} [override=false] Whether to override existing comments at
+   *   the target location. If false, comments will be appended.
+   *
+   * @throws {TypeError} If source is not an object.
+   *
+   * @example
+   * const obj = parse('{"a": 1 // comment on a}')
+   *
+   * // Move comment from after 'a' to before 'a'
+   * moveComments(obj, obj,
+   *   { kind: 'after', key: 'a' },
+   *   { kind: 'before', key: 'a' }
+   * )
+   *
+   * @example
+   * // Move non-property comment
+   * moveComments(obj, obj,
+   *   { kind: 'before-all' },
+   *   { kind: 'after-all' }
+   * )
+   */
   moveComments (source, target, {
     kind: from_kind,
     key: from_key
diff --git a/src/parse.js b/src/parse.js
@@ -32,6 +32,17 @@ const {
   assign_non_prop_comments
 } = require('./common')
 
+/**
+ * Tokenize JSON string with comments into an array of tokens.
+ *
+ * @param {string} code The JSON string with comments to tokenize.
+ * @returns {Array} Array of token objects containing type, value, and location
+ *   information.
+ *
+ * @example
+ * const tokens = tokenize('{"a": 1 // comment}')
+ * // Returns array of tokens including comment tokens
+ */
 const tokenize = code => esprima.tokenize(code, {
   comment: true,
   loc: true
@@ -417,7 +428,35 @@ function walk () {
 
 const isObject = subject => Object(subject) === subject
 
-// TODO: js doc and usage examples
+/**
+ * Converts a JavaScript Object Notation (JSON) string with comments into an
+ * object.
+ *
+ * @param {string} code A valid JSON string with comments.
+ * @param {function} [rev] A function that transforms the results. This function
+ *   is called for each member of the object. If a member contains nested
+ *   objects, the nested objects are transformed before the parent object is.
+ * @param {boolean} [no_comments=false] If true, the comments won't be
+ *   maintained, which is often used when we want to get a clean object.
+ * @returns {*} The JavaScript object corresponding to the given JSON text with
+ *   comments preserved as symbol properties.
+ *
+ * @example
+ * const result = parse('{"a": 1 // This is a comment}')
+ * // result.a === 1
+ * // Comments are stored in symbol properties
+ *
+ * @example
+ * // With reviver function
+ * const result = parse('{"a": "1"}', (key, value) => {
+ *   return typeof value === 'string' ? parseInt(value) : value
+ * })
+ *
+ * @example
+ * // Without comments
+ * const clean = parse('{"a": 1 // comment}', null, true)
+ * // Returns clean object without comment symbols
+ */
 const parse = (code, rev, no_comments) => {
   // Clean variables in closure
   clean()
diff --git a/src/stringify.js b/src/stringify.js
@@ -332,10 +332,33 @@ const is_primitive_object = subject => {
   return PRIMITIVE_OBJECT_TYPES.includes(str)
 }
 
-// TODO: js doc and usage examples
-
-// @param {function()|Array} replacer
-// @param {string|number} space
+/**
+ * Converts a JavaScript value to a JavaScript Object Notation (JSON) string
+ * with comments preserved.
+ *
+ * @param {*} value A JavaScript value, usually an object or array, to be
+ *   converted.
+ * @param {function|Array|null} [replacer_] A function that transforms the
+ *   results or an array of strings and numbers that acts as an approved list
+ *   for selecting the object properties that will be stringified.
+ * @param {string|number} [space] Adds indentation, white space, and line
+ *   break characters to the return-value JSON text to make it easier to read.
+ * @returns {string} A JSON string representing the given value with comments
+ *   preserved.
+ *
+ * @example
+ * const obj = parse('{"a": 1 // comment}')
+ * stringify(obj, null, 2)
+ * // Returns: '{\n  "a": 1 // comment\n}'
+ *
+ * @example
+ * // With replacer function
+ * stringify(obj, (key, value) => typeof value === 'number' ? value * 2 : value)
+ *
+ * @example
+ * // With replacer array
+ * stringify(obj, ['a', 'b']) // Only include 'a' and 'b' properties
+ */
 module.exports = (value, replacer_, space) => {
   // The stringify method takes a value and an optional replacer, and an optional
   // space parameter, and returns a JSON text. The replacer can be a function
