Add improved docs

wooorm · wooorm · commit d10a468d3e90 · 2023-02-08T20:30:28.000+01:00
diff --git a/index.d.ts b/index.d.ts
@@ -11,12 +11,13 @@ type MaybeBuffer = any extends Buffer ? never : Buffer
 
 /**
  * Contents of the file.
- * Can either be text, or a Buffer like structure.
- * This does not directly use type `Buffer`, because it can also be used in a
- * browser context.
- * Instead this leverages `Uint8Array` which is the base type for `Buffer`,
- * and a native JavaScript construct.
+ *
+ * Can either be text or a `Buffer` structure.
  */
+// Note: this does not directly use type `Buffer`, because it can also be used
+// in a browser context.
+// Instead this leverages `Uint8Array` which is the base type for `Buffer`,
+// and a native JavaScript construct.
 export type Value = string | MaybeBuffer
 
 /**
@@ -37,7 +38,7 @@ export type Value = string | MaybeBuffer
 export interface DataMap {}
 
 /**
- * Place to store custom information.
+ * Custom information.
  *
  * Known attributes can be added to @see {@link DataMap}
  */
diff --git a/lib/index.js b/lib/index.js
@@ -17,7 +17,7 @@
  *   being needed.
  *   Copied from: <https://github.com/DefinitelyTyped/DefinitelyTyped/blob/90a4ec8/types/node/buffer.d.ts#L170>
  *
- * @typedef {Value | Options | VFile | URL} Compatible
+ * @typedef {Options | URL | Value | VFile} Compatible
  *   Things that can be passed to the constructor.
  *
  * @typedef VFileCoreOptions
@@ -42,7 +42,9 @@
  *   Set `data`.
  *
  * @typedef Map
- *   Raw source map, see:
+ *   Raw source map.
+ *
+ *   See:
  *   <https://github.com/mozilla/source-map/blob/58819f0/source-map.d.ts#L15-L23>.
  * @property {number} version
  *   Which version of the source map spec this map is following.
@@ -72,7 +74,7 @@
  * @template {ReporterSettings} Settings
  *   Options type.
  * @callback Reporter
- *   Type for a report.
+ *   Type for a reporter.
  * @param {Array<VFile>} files
  *   Files to report.
  * @param {Settings} options
@@ -403,7 +405,7 @@ export class VFile {
   }
 
   /**
-   * Create an informational message associated with the file.
+   * Create an info message associated with the file.
    *
    * Its `fatal` is set to `null` and `file` is set to the current file path.
    * Its added to `file.messages`.
@@ -443,6 +445,8 @@ export class VFile {
    *   `'my-package:my-rule'` or `'my-rule'`).
    * @returns {never}
    *   Message.
+   * @throws {VFileMessage}
+   *   Message.
    */
   fail(reason, place, origin) {
     const message = this.message(reason, place, origin)
diff --git a/readme.md b/readme.md
