Refactor docs

lib/index.js

@@ -1,24 +1,40 @@
+// To do: remove `void`s
+// To do: remove `null` from output of our APIs, allow it as user APIs.
+
 /**
  * @typedef {(error?: Error | null | undefined, ...output: Array<any>) => void} Callback
  *   Callback.
  *
  * @typedef {(...input: Array<any>) => any} Middleware
  *   Ware.
  *
- * @typedef {{run: Run, use: Use}} Pipeline
- *   Middleware.
+ * @typedef Pipeline
+ *   Pipeline.
+ * @property {Run} run
+ *   Run the pipeline.
+ * @property {Use} use
+ *   Add middleware.
  *
  * @typedef {(...input: Array<any>) => void} Run
  *   Call all middleware.
+ *
+ *   Calls `done` on completion with either an error or the output of the
+ *   last middleware.
+ *
+ *   > 👉 **Note**: as the length of input defines whether async functions get a
+ *   > `next` function,
+ *   > it’s recommended to keep `input` at one value normally.
+
  *
  * @typedef {(fn: Middleware) => Pipeline} Use
- *   Add `fn` (middleware) to the list.
+ *   Add middleware.
  */
 
 /**
  * Create new middleware.
  *
  * @returns {Pipeline}
+ *   Pipeline.
  */
 export function trough() {
   /** @type {Array<Middleware>} */
@@ -88,12 +104,36 @@ export function trough() {
 }
 
 /**
- * Wrap `middleware`.
- * Can be sync or async; return a promise, receive a callback, or return new
- * values and errors.
+ * Wrap `middleware` into a uniform interface.
+ *
+ * You can pass all input to the resulting function.
+ * `callback` is then called with the output of `middleware`.
+ *
+ * If `middleware` accepts more arguments than the later given in input,
+ * an extra `done` function is passed to it after that input,
+ * which must be called by `middleware`.
+ *
+ * The first value in `input` is the main input value.
+ * All other input values are the rest input values.
+ * The values given to `callback` are the input values,
+ * merged with every non-nullish output value.
+ *
+ * * if `middleware` throws an error,
+ *   returns a promise that is rejected,
+ *   or calls the given `done` function with an error,
+ *   `callback` is called with that error
+ * * if `middleware` returns a value or returns a promise that is resolved,
+ *   that value is the main output value
+ * * if `middleware` calls `done`,
+ *   all non-nullish values except for the first one (the error) overwrite the
+ *   output values
  *
  * @param {Middleware} middleware
+ *   Function to wrap.
  * @param {Callback} callback
+ *   Callback called with the output of `middleware`.
+ * @returns {Run}
+ *   Wrapped middleware.
  */
 export function wrap(middleware, callback) {
   /** @type {boolean} */
@@ -145,6 +185,7 @@ export function wrap(middleware, callback) {
 
   /**
    * Call `callback`, only once.
+   *
    * @type {Callback}
    */
   function done(error, ...output) {