Add improved docs

index.js

@@ -82,6 +82,10 @@ export class VFileMessage extends Error {
     /**
      * Whether this is a fatal problem that marks an associated file as no
      * longer processable.
+     * If `true`, marks associated file as no longer processable.
+     * If `false`, necessitates a (potential) change.
+     * The value can also be `null` or `undefined`, for things that might not
+     * need changing.
      *
      * @type {boolean?}
      */
@@ -102,30 +106,30 @@ export class VFileMessage extends Error {
     this.column = position.start.column
 
     /**
-     * Namespace of warning.
+     * Full range information, when available.
+     * Has `start` and `end` fields, both set to an object with `line` and
+     * `column`, set to `number?`.
      *
-     * @type {string?}
+     * @type {Position?}
      */
-    this.source = parts[0]
+    this.position = position
 
     /**
-     * Category of message.
+     * Namespace of warning (example: `'my-package'`).
      *
      * @type {string?}
      */
-    this.ruleId = parts[1]
+    this.source = parts[0]
 
     /**
-     * Full range information, when available.
-     * Has `start` and `end` fields, both set to an object with `line` and
-     * `column`, set to `number?`.
+     * Category of message (example: `'my-rule-name'`).
      *
-     * @type {Position?}
+     * @type {string?}
      */
-    this.position = position
+    this.ruleId = parts[1]
 
     /**
-     * A path of a file (used throughout the VFile ecosystem).
+     * Path of a file (used throughout the VFile ecosystem).
      *
      * @type {string?}
      */

readme.md

@@ -10,24 +10,60 @@
 
 Create [vfile][] messages.
 
-## Install
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`VFileMessage(reason[, place][, origin])`](#vfilemessagereason-place-origin)
+    *   [Well-known fields](#well-known-fields)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Contribute](#contribute)
+*   [License](#license)
+
+## What is this?
+
+This package provides a (lint) message format.
 
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
-Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
+## When should I use this?
+
+In most cases, you can use `file.message` from `VFile` itself, but in some
+cases you might not have a file, and still want to emit warnings or errors,
+in which case this can be used directly.
+
+## Install
 
-[npm][]:
+This package is [ESM only][esm].
+In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with [npm][]:
 
-```bash
+```sh
 npm install vfile-message
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {VFileMessage} from 'https://esm.sh/vfile-message@3'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {VFileMessage} from 'https://esm.sh/vfile-message@3?bundle'
+</script>
+```
+
 ## Use
 
 ```js
 import {VFileMessage} from 'vfile-message'
 
-var message = new VFileMessage(
-  '`braavo` is misspelt; did you mean `bravo`?',
+const message = new VFileMessage(
+  'Unexpected unknown word `braavo`, did you mean `bravo`?',
   {line: 1, column: 8},
   'spell:typo'
 )
@@ -38,8 +74,8 @@ console.log(message)
 Yields:
 
 ```txt
-[1:8: `braavo` is misspelt; did you mean `bravo`?] {
-  reason: '`braavo` is misspelt; did you mean `bravo`?',
+[1:8: Unexpected unknown word `braavo`, did you mean `bravo`?] {
+  reason: 'Unexpected unknown word `braavo`, did you mean `bravo`?',
   line: 1,
   column: 8,
   source: 'spell',
@@ -50,13 +86,13 @@ Yields:
 
 ## API
 
-This package exports the following identifiers: `VFileMessage`.
+This package exports the identifier `VFileMessage`.
 There is no default export.
 
 ### `VFileMessage(reason[, place][, origin])`
 
-Constructor of a message for `reason` at `place` from `origin`.
-When an error is passed in as `reason`, copies the stack.
+Create a message for `reason` at `place` from `origin`.
+When an error is passed in as `reason`, the `stack` is copied.
 
 ##### Parameters
 
@@ -94,9 +130,12 @@ Reason for message (`string`).
 
 ###### `fatal`
 
-If `true`, marks associated file as no longer processable (`boolean?`).
+Whether this is a fatal problem that marks an associated file as no longer
+processable (`boolean?`).
+If `true`, marks associated file as no longer processable.
 If `false`, necessitates a (potential) change.
-The value can also be `null` or `undefined`.
+The value can also be `null` or `undefined`, for things that might not need
+changing.
 
 ###### `line`
 
@@ -114,44 +153,55 @@ Has `start` and `end` properties, both set to an object with `line` and
 
 ###### `source`
 
-Namespace of message (`string?`).
+Namespace of message (`string?`, example: `'my-package'`).
 
 ###### `ruleId`
 
-Category of message (`string?`).
+Category of message (`string?`, example: `'my-rule-name'`).
 
 ###### `stack`
 
 Stack of message (`string?`).
 
-##### Custom properties
+###### `file`
+
+Path of a file (used throughout the vfile ecosystem).
+
+### Well-known fields
 
 It’s OK to store custom data directly on the `VFileMessage`, some of those are
 handled by [utilities][util].
 
 ###### `actual`
 
-You can use this to specify the source value that’s being reported, which is
-deemed incorrect.
+Specify the source value that’s being reported, which is deemed incorrect
+(`string?`).
 
 ###### `expected`
 
-You can use this to suggest values that should be used instead of `actual`, one
-or more values that are deemed as acceptable.
+Suggest values that should be used instead of `actual`, one or more values that
+are deemed as acceptable (`(string|Array<string>)?`)
 
-###### `file`
+###### `url`
 
-You may add a `file` property with a path of a file (used throughout the
-[**VFile**][vfile] ecosystem).
+Link to documentation for the message (`string`).
 
 ###### `note`
 
-You may add a `note` property with a long form description of the message
-(supported by [`vfile-reporter`][reporter]).
+Long form description of the message (supported by
+[`vfile-reporter`][reporter]).
 
-###### `url`
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports no additional types.
+
+## Compatibility
 
-You may add a `url` property with a link to documentation for the message.
+Projects maintained by the unified collective are compatible with all maintained
+versions of Node.js.
+As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
+Our projects sometimes work with older versions, but this is not guaranteed.
 
 ## Contribute
 
@@ -197,13 +247,19 @@ abide by its terms.
 
 [npm]: https://docs.npmjs.com/cli/install
 
-[contributing]: https://github.com/vfile/.github/blob/HEAD/contributing.md
+[contributing]: https://github.com/vfile/.github/blob/main/contributing.md
 
-[support]: https://github.com/vfile/.github/blob/HEAD/support.md
+[support]: https://github.com/vfile/.github/blob/main/support.md
 
 [health]: https://github.com/vfile/.github
 
-[coc]: https://github.com/vfile/.github/blob/HEAD/code-of-conduct.md
+[coc]: https://github.com/vfile/.github/blob/main/code-of-conduct.md
+
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[typescript]: https://www.typescriptlang.org
 
 [license]: license