Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null` in input of API types

Author: wooorm

lib/index.js

@@ -3,21 +3,26 @@
  * @typedef {import('vfile').VFileOptions} Options
  * @typedef {import('vfile').BufferEncoding} BufferEncoding
  *
- * @typedef {number|string} Mode
- * @typedef {BufferEncoding|{encoding?: null|BufferEncoding, flag?: string}} ReadOptions
- * @typedef {BufferEncoding|{encoding?: null|undefined|BufferEncoding, mode?: Mode | undefined, flag?: string | undefined}} WriteOptions
+ * @typedef {number | string} Mode
+ * @typedef {{encoding?: BufferEncoding | null | undefined, flag?: string | undefined}} ReadOptions
+ * @typedef {{encoding?: null | undefined | BufferEncoding, mode?: Mode | undefined, flag?: string | undefined}} WriteOptions
  *
- * @typedef {URL|Value} Path
- *   Path of the file.
- *   Note: `Value` is used here because it’s a smarter `Buffer`
- * @typedef {Path|Options|VFile} Compatible
- *   Things that can be passed to the function.
+ *
+ * @typedef {URL | Value} Path
+ *   URL to file or path to file.
+ *
+ *   > 👉 **Note**: `Value` is used here because it’s a smarter `Buffer`
+ * @typedef {Path | Options | VFile} Compatible
+ *   URL to file, path to file, options for file, or actual file.
  */
 
 /**
  * @callback Callback
- * @param {NodeJS.ErrnoException|null} error
+ *   Callback called after reading or writing a file.
+ * @param {NodeJS.ErrnoException | null} error
+ *   Error when reading or writing was not successful.
  * @param {VFile | null | undefined} file
+ *   File when reading or writing was successful.
  */
 
 import fs from 'fs'
@@ -26,31 +31,44 @@ import {URL} from 'url'
 import buffer from 'is-buffer'
 import {VFile} from 'vfile'
 
+// To do: next major: use `node:` prefix.
+// To do: next major: use `URL` from global.
+// To do: next major: Only pass `undefined`.
+
 /**
  * Create a virtual file from a description.
- * If `options` is a string or a buffer, it’s used as the path.
- * If it’s a VFile itself, it’s returned instead.
- * In all other cases, the options are passed through to `vfile()`.
  *
- * @param {Compatible} [options]
+ * If `options` is a string, URL, or buffer, it’s used as the path.
+ * Otherwise, if it’s a `VFile`, that’s returned instead.
+ * Otherwise, the options are passed through to `new VFile()`.
+ *
+ * @param {Compatible | null | undefined} [description]
+ *   Path to file, file options, or file itself.
  * @returns {VFile}
+ *   Given `VFile` or new `VFile`.
  */
-export function toVFile(options) {
-  if (typeof options === 'string' || options instanceof URL) {
-    options = {path: options}
-  } else if (buffer(options)) {
-    options = {path: String(options)}
+export function toVFile(description) {
+  if (typeof description === 'string' || description instanceof URL) {
+    description = {path: description}
+  } else if (buffer(description)) {
+    description = {path: String(description)}
   }
 
-  return looksLikeAVFile(options) ? options : new VFile(options)
+  return looksLikeAVFile(description)
+    ? description
+    : // To do: remove when `VFile` allows explicit `null`.
+      new VFile(description || undefined)
 }
 
 /**
  * Create a virtual file and read it in, synchronously.
  *
  * @param {Compatible} description
- * @param {ReadOptions} [options]
+ *   Path to file, file options, or file itself.
+ * @param {BufferEncoding | ReadOptions | null | undefined} [options]
+ *   Encoding to use or Node.JS read options.
  * @returns {VFile}
+ *   Given `VFile` or new `VFile`.
  */
 export function readSync(description, options) {
   const file = toVFile(description)
@@ -59,33 +77,47 @@ export function readSync(description, options) {
 }
 
 /**
- * Create a virtual file and write it in, synchronously.
+ * Create a virtual file and write it, synchronously.
  *
  * @param {Compatible} description
- * @param {WriteOptions} [options]
+ *   Path to file, file options, or file itself.
+ * @param {BufferEncoding | WriteOptions | null | undefined} [options]
+ *   Encoding to use or Node.JS write options.
  * @returns {VFile}
+ *   Given `VFile` or new `VFile`.
  */
 export function writeSync(description, options) {
   const file = toVFile(description)
   fs.writeFileSync(path.resolve(file.cwd, file.path), file.value || '', options)
   return file
 }
 
+/**
+ * Create a virtual file and read it in, async.
+ *
+ * @param description
+ *   Path to file, file options, or file itself.
+ * @param options
+ *   Encoding to use or Node.JS read options.
+ * @param callback
+ *   Callback called when done.
+ * @returns
+ *   Nothing when a callback is given, otherwise promise that resolves to given
+ *   `VFile` or new `VFile`.
+ */
 export const read =
   /**
    * @type {{
-   *   (description: Compatible, options: ReadOptions, callback: Callback): void
+   *   (description: Compatible, options: BufferEncoding | ReadOptions, callback: Callback): void
    *   (description: Compatible, callback: Callback): void
-   *   (description: Compatible, options?: ReadOptions): Promise<VFile>
+   *   (description: Compatible, options?: BufferEncoding | ReadOptions | null | undefined): Promise<VFile>
    * }}
    */
   (
     /**
-     * Create a virtual file and read it in, asynchronously.
-     *
      * @param {Compatible} description
-     * @param {ReadOptions | null} [options]
-     * @param {Callback} [callback]
+     * @param {BufferEncoding | ReadOptions | null | undefined} [options]
+     * @param {Callback | null | undefined} [callback]
      */
     function (description, options, callback) {
       const file = toVFile(description)
@@ -142,21 +174,32 @@ export const read =
     }
   )
 
+/**
+ * Create a virtual file and write it, async.
+ *
+ * @param description
+ *   Path to file, file options, or file itself.
+ * @param options
+ *   Encoding to use or Node.JS write options.
+ * @param callback
+ *   Callback called when done.
+ * @returns
+ *   Nothing when a callback is given, otherwise promise that resolves to given
+ *   `VFile` or new `VFile`.
+ */
 export const write =
   /**
    * @type {{
-   *   (description: Compatible, options: WriteOptions, callback: Callback): void
+   *   (description: Compatible, options: BufferEncoding | WriteOptions, callback: Callback): void
    *   (description: Compatible, callback: Callback): void
-   *   (description: Compatible, options?: WriteOptions): Promise<VFile>
+   *   (description: Compatible, options?: BufferEncoding | WriteOptions | null | undefined): Promise<VFile>
    * }}
    */
   (
     /**
-     * Create a virtual file and write it in, asynchronously.
-     *
      * @param {Compatible} description
-     * @param {WriteOptions} [options]
-     * @param {Callback} [callback]
+     * @param {BufferEncoding | WriteOptions | null | undefined} [options]
+     * @param {Callback | null | undefined} [callback]
      */
     function (description, options, callback) {
       const file = toVFile(description)
@@ -213,8 +256,12 @@ export const write =
   )
 
 /**
- * @param {Compatible | undefined} value
+ * Check if something looks like a vfile.
+ *
+ * @param {Compatible | null | undefined} value
+ *   Value.
  * @returns {value is VFile}
+ *   Whether `value` looks like a `VFile`.
  */
 function looksLikeAVFile(value) {
   return Boolean(