Add improved docs

index.js

@@ -1,10 +1,14 @@
 /**
- * @typedef {import('./lib/index.js').Compatible} Compatible
- * @typedef {import('./lib/index.js').Callback} Callback
  * @typedef {import('./lib/index.js').BufferEncoding} BufferEncoding
- * @typedef {import('./lib/index.js').Mode} Mode
+ * @typedef {import('./lib/index.js').Callback} Callback
+ * @typedef {import('./lib/index.js').Compatible} Compatible
  * @typedef {import('./lib/index.js').ReadOptions} ReadOptions
  * @typedef {import('./lib/index.js').WriteOptions} WriteOptions
  */
 
+// To do: next major: don’t expose `Mode`.
+/**
+ * @typedef {number | string} Mode
+ */
+
 export {toVFile, read, readSync, write, writeSync} from './lib/index.js'

lib/index.js

@@ -2,11 +2,25 @@
  * @typedef {import('vfile').VFileValue} Value
  * @typedef {import('vfile').VFileOptions} Options
  * @typedef {import('vfile').BufferEncoding} BufferEncoding
+ *   Encodings supported by the buffer class.
  *
- * @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
+ *   This is a copy of the types from Node and `VFile`.
  *
+ * @typedef ReadOptions
+ *   Configuration for `fs.readFile`.
+ * @property {BufferEncoding | null | undefined} [encoding]
+ *   Encoding to read file as, will turn `file.value` into a string if passed.
+ * @property {string | undefined} [flag]
+ *   File system flags to use.
+ *
+ * @typedef WriteOptions
+ *   Configuration for `fs.writeFile`.
+ * @property {BufferEncoding | null | undefined} [encoding]
+ *   Encoding to write file as.
+ * @property {number | string | undefined} [mode]
+ *   File mode (permission and sticky bits) if the file was newly created.
+ * @property {string | undefined} [flag]
+ *   File system flags to use.
  *
  * @typedef {URL | Value} Path
  *   URL to file or path to file.
@@ -38,14 +52,16 @@ import {VFile} from 'vfile'
 /**
  * Create a virtual file from a description.
  *
+ * This is like `VFile`, but it accepts a file path instead of file cotnents.
+ *
  * 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, if it’s a file, 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`.
+ *   Given file or new file.
  */
 export function toVFile(description) {
   if (typeof description === 'string' || description instanceof URL) {
@@ -68,7 +84,7 @@ export function toVFile(description) {
  * @param {BufferEncoding | ReadOptions | null | undefined} [options]
  *   Encoding to use or Node.JS read options.
  * @returns {VFile}
- *   Given `VFile` or new `VFile`.
+ *   Given file or new file.
  */
 export function readSync(description, options) {
   const file = toVFile(description)
@@ -84,7 +100,7 @@ export function readSync(description, options) {
  * @param {BufferEncoding | WriteOptions | null | undefined} [options]
  *   Encoding to use or Node.JS write options.
  * @returns {VFile}
- *   Given `VFile` or new `VFile`.
+ *   Given file or new file.
  */
 export function writeSync(description, options) {
   const file = toVFile(description)
@@ -103,12 +119,12 @@ export function writeSync(description, options) {
  *   Callback called when done.
  * @returns
  *   Nothing when a callback is given, otherwise promise that resolves to given
- *   `VFile` or new `VFile`.
+ *   file or new file.
  */
 export const read =
   /**
    * @type {{
-   *   (description: Compatible, options: BufferEncoding | ReadOptions, callback: Callback): void
+   *   (description: Compatible, options: BufferEncoding | ReadOptions | null | undefined, callback: Callback): void
    *   (description: Compatible, callback: Callback): void
    *   (description: Compatible, options?: BufferEncoding | ReadOptions | null | undefined): Promise<VFile>
    * }}
@@ -185,12 +201,12 @@ export const read =
  *   Callback called when done.
  * @returns
  *   Nothing when a callback is given, otherwise promise that resolves to given
- *   `VFile` or new `VFile`.
+ *   file or new file.
  */
 export const write =
   /**
    * @type {{
-   *   (description: Compatible, options: BufferEncoding | WriteOptions, callback: Callback): void
+   *   (description: Compatible, options: BufferEncoding | WriteOptions | null | undefined, callback: Callback): void
    *   (description: Compatible, callback: Callback): void
    *   (description: Compatible, options?: BufferEncoding | WriteOptions | null | undefined): Promise<VFile>
    * }}
@@ -272,6 +288,7 @@ function looksLikeAVFile(value) {
   )
 }
 
+// To do: next major: remove?
 toVFile.readSync = readSync
 toVFile.writeSync = writeSync
 toVFile.read = read