From 99787d35fa936e9fbde81cc80225971a181ffcad Mon Sep 17 00:00:00 2001
From: Titus Wormer <tituswormer@gmail.com>
Date: Sun, 7 Nov 2021 10:03:30 +0100
Subject: [PATCH] Update docs

---
 index.js             |   6 +++
 readme.md            | 111 +++++++++++++++++++++++++++++++++++++++----
 script/build-data.js |   6 +++
 3 files changed, 115 insertions(+), 8 deletions(-)

diff --git a/index.js b/index.js
index 162c58e..aff0a2b 100644
--- a/index.js
+++ b/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.
  */
 
 /**
diff --git a/readme.md b/readme.md
index 27fbac7..f566343 100644
--- a/readme.md
+++ b/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
diff --git a/script/build-data.js b/script/build-data.js
index 8fc77cc..8d8ab5f 100644
--- a/script/build-data.js
+++ b/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.',
     ' */',
     '',
     '/**',