Update docs

index.js

@@ -1,10 +1,16 @@
 /**
  * @typedef Emoticon
+ *   Info on an emoticon.
  * @property {string} name
+ *   Name of an emoticon (preferred name from `wooorm/gemoji`).
  * @property {string} emoji
+ *   Corresponding emoji.
  * @property {Array<string>} tags
+ *   Associated tags (from `wooorm/gemoji`).
  * @property {string} description
+ *   Associated description (from `wooorm/gemoji`).
  * @property {Array<string>} emoticons
+ *   ASCII emoticons.
  */
 
 /**

readme.md

@@ -5,19 +5,57 @@
 [![Downloads][downloads-badge]][downloads]
 [![Size][size-badge]][size]
 
-Info on ASCII emoticons.  :p
+List of emoticons.
 
-## Install
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`emoticon`](#emoticon-1)
+*   [Types](#types)
+*   [List of emoticons](#list-of-emoticons)
+*   [Compatibility](#compatibility)
+*   [Security](#security)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [License](#license)
+
+## What is this?
+
+This package contains info on ASCII emoticons.
+:p
 
-This package is ESM only: Node 12+ is needed to use it and it must be `import`ed
-instead of `require`d.
+## When should I use this?
 
-[npm][]:
+You can use this package for several reasons, typically in a build script,
+for example to figure out which text emoticons map to what emoji.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
 
 ```sh
 npm install emoticon
 ```
 
+In Deno with [Skypack][]:
+
+```js
+import {emoticon} from 'https://cdn.skypack.dev/emoticon@4?dts'
+```
+
+In browsers with [Skypack][]:
+
+```html
+<script type="module">
+  import {emoticon} from 'https://cdn.skypack.dev/emoticon@4?min'
+</script>
+```
+
 ## Use
 
 ```js
@@ -61,15 +99,62 @@ Yields:
 
 ## API
 
-This package exports the following identifiers: `emoticon`.
+This package exports the following identifier: `emoticon`.
 There is no default export.
 
-See use above for an example.
+### `emoticon`
+
+List of emoticons (`Array<Emoticon>`), where each entry has the following
+fields:
+
+*   `name` (`string`)
+    — name of an emoticon (preferred name from [`wooorm/gemoji`][gemoji])
+*   `emoji` (`string`)
+    — corresponding emoji
+*   `tags` (`Array<string>`)
+    — associated tags (from [`wooorm/gemoji`][gemoji])
+*   `description` (`string`)
+    — associated description (from [`wooorm/gemoji`][gemoji])
+*   `emoticons` (`Array<string>`)
+    — ASCII emoticons
 
-## Support
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports an additional `Emoticon` type that models its respective interface.
+
+## List of emoticons
 
 See [`support.md`][support].
 
+## Compatibility
+
+This package is at least compatible with all maintained versions of Node.js.
+As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
+It also works in Deno and modern browsers.
+
+## Security
+
+This package is safe.
+
+## Related
+
+*   [`wooorm/gemoji`][gemoji]
+    — info on gemoji (GitHub emoji)
+*   [`words/emoji-emotion`](https://github.com/words/emoji-emotion)
+    — list of emoji rated for valence
+*   [`wooorm/emoticon`](https://github.com/wooorm/emoticon)
+    — info on ASCII emoticons
+*   [`wooorm/strip-skin-tone`](https://github.com/wooorm/strip-skin-tone)
+    — strip skin-tones from emoji
+*   [`wooorm.com/checkmoji`](https://wooorm.com/checkmoji/)
+    — check emoji across platforms
+
+## Contribute
+
+Yes please!
+See [How to Contribute to Open Source][contribute].
+
 ## License
 
 [MIT][license] © [Titus Wormer][author]
@@ -94,8 +179,18 @@ See [`support.md`][support].
 
 [npm]: https://docs.npmjs.com/cli/install
 
+[skypack]: https://www.skypack.dev
+
 [license]: license
 
 [author]: https://wooorm.com
 
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[typescript]: https://www.typescriptlang.org
+
+[contribute]: https://opensource.guide/how-to-contribute/
+
 [support]: support.md
+
+[gemoji]: https://github.com/wooorm/gemoji

script/build-data.js

@@ -94,11 +94,17 @@ fs.writeFileSync(
   [
     '/**',
     ' * @typedef Emoticon',
+    ' *   Info on an emoticon.',
     ' * @property {string} name',
+    ' *   Name of an emoticon (preferred name from `wooorm/gemoji`).',
     ' * @property {string} emoji',
+    ' *   Corresponding emoji.',
     ' * @property {Array<string>} tags',
+    ' *   Associated tags (from `wooorm/gemoji`).',
     ' * @property {string} description',
+    ' *   Associated description (from `wooorm/gemoji`).',
     ' * @property {Array<string>} emoticons',
+    ' *   ASCII emoticons.',
     ' */',
     '',
     '/**',