Add improved docs

Author: wooorm

index.js

@@ -1,16 +1,28 @@
 /**
  * @typedef Options
+ *   Configuration (optional).
+ * @property {boolean} [keepSpaces=false]
+ *   Keep superfluous whitespace.
+ *   Whitespace is turned into a space by default.
  * @property {Array<string>} [stopwords]
- * @property {boolean} [keepSpaces]
+ *   List of stopwords.
+ *   When a lowercased word is included in this list, it will be used as
+ *   lowercase.
+ *   Otherwise words are capitalized.
  */
 
 const stopwords = 'a an and at but by for in nor of on or so the to up yet'
 const defaults = stopwords.split(' ')
 
 /**
+ * Convert a value to title case using AP/APA style.
+ *
  * @param {string} [value]
+ *   Short text of unknown casing.
  * @param {Options} [options]
+ *   Configuration (optional).
  * @returns {string}
+ *   Title-cased version of `value`.
  */
 export function apStyleTitleCase(value, options) {
   const configuration = options || {}
@@ -26,13 +38,10 @@ export function apStyleTitleCase(value, options) {
     .map((word, index, all) => {
       if (/\s+/.test(word)) return keep ? word : ' '
       if (splitter.test(word)) return word
+      const lower = word.toLowerCase()
 
-      if (
-        index !== 0 &&
-        index !== all.length - 1 &&
-        stop.includes(word.toLowerCase())
-      ) {
-        return word.toLowerCase()
+      if (index !== 0 && index !== all.length - 1 && stop.includes(lower)) {
+        return lower
       }
 
       return capitalize(word)

readme.md

@@ -5,22 +5,61 @@
 [![Downloads][downloads-badge]][downloads]
 [![Size][size-badge]][size]
 
-Convert a value to title case using [AP][]/[APA][] style.
+Convert a value to [AP][]/[APA][] title case.
+
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`apStyleTitleCase(value[, options])`](#apstyletitlecasevalue-options)
+*   [Algorithm](#algorithm)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Contribute](#contribute)
+*   [Security](#security)
+*   [License](#license)
+
+## What is this?
+
+This small package turns a sentence into title case.
+
+## When should I use this?
+
+You can use this when you have short text of unknown casing and want to display
+it in a heading or so.
 
 ## Install
 
-[npm][]:
+This package is [ESM only][esm].
+In Node.js (version 14.14+, 16.0+), install with [npm][]:
 
-```bash
+```sh
 npm install ap-style-title-case
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {apStyleTitleCase} from 'https://esm.sh/ap-style-title-case@1'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {apStyleTitleCase} from 'https://esm.sh/ap-style-title-case@1?bundle'
+</script>
+```
+
 ## Use
 
 ```js
-var titleCase = require('ap-style-title-case')
+import {apStyleTitleCase} from 'ap-style-title-case'
 
-console.log(titleCase('why sunless tanning is A hot trend'))
+console.log(apStyleTitleCase('why sunless tanning is A hot trend'))
 // 'Why Sunless Tanning Is a Hot Trend'
 ```
 
@@ -30,25 +69,35 @@ console.log(titleCase('why sunless tanning is A hot trend'))
 
 Convert a value (`string`) to title case (`string`) using [AP][]/[APA][] style.
 
-*   `options.keepSpaces` (`boolean`, default: `false`)
-    — Superfluous whitespace is ignored by default, turn this on to allow it
-*   `options.stopwords` (`Array.<string>`, default: see list below)
-    — Lowercase the given stop words instead of the defaults
+##### `options`
+
+Configuration (optional).
+
+###### `options.keepSpaces`
 
-## The Rules
+Keep superfluous whitespace (`boolean`, default: `false`).
+Whitespace is turned into a space by default.
 
-*   Always capitalize the first word, even if it’s a stop word
-*   Always capitalize the last word, even if it’s a stop word
-*   Lowercase these words: `a an and at but by for in nor of on or so the to up
-    yet`
+###### `options.stopwords`
 
-> Many writers make the error of leaving “to be” verbs in lower case.
-> Even though “is,” “are,” “was,” and “be,” are all short words, they should
+List of stopwords (`Array<string>`, default: see below).
+When a lowercased word is included in this list, it will be used as lowercase.
+Otherwise words are capitalized.
+
+## Algorithm
+
+*   always capitalize the first word, even if it’s a stop word
+*   always capitalize the last word, even if it’s a stop word
+*   lowercase these words: `a`, `an`, `and`, `at`, `but`, `by`, `for`, `in`,
+    `nor`, `of`, `on`, `or`, `so`, `the`, `to`, `up`, `yet`
+
+> Many writers make the error of leaving `to be` verbs in lower case.
+> Even though `is`, `are`, `was`, and `be`, are all short words, they should
 > still be capitalized in a title because they are verbs.
 >
 > When you write titles that contain prepositions, your word processor will
-> likely tell you that you should leave words like “with,” “about,” and “around”
-> lowercase.
+> likely tell you that you should leave words like `with`, `about`, and
+> `around` lowercase.
 > Defiantly look past the squiggly line indicating a potential error, and
 > remember that in AP title case, prepositions with four or more letters should
 > be capitalized.
@@ -57,12 +106,34 @@ Convert a value (`string`) to title case (`string`) using [AP][]/[APA][] style.
 > AP style does not recommend the use of title case for newspaper headlines, but
 > rather sentence case.
 
-## References
+###### References
+
+*   [*How to correctly use AP (and APA) style title case* on
+    `bkacontent.com`](https://www.bkacontent.com/how-to-correctly-use-apa-style-title-case/)
+*   [*AP Stylebook* on `wikipedia.com`](https://en.wikipedia.org/wiki/AP_Stylebook)
+*   [*APA style* on `wikipedia.com`](https://en.wikipedia.org/wiki/APA_style)
+*   [*Title case and sentence case capitalization in APA style* on
+    `apastyle.org`](http://blog.apastyle.org/apastyle/2012/03/title-case-and-sentence-case-capitalization-in-apa-style.html)
+
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional type `Options`.
+
+## Compatibility
+
+This package is at least compatible with all maintained versions of Node.js.
+As of now, that is Node.js 14.14+ and 16.0+.
+It also works in Deno and modern browsers.
 
-*   <https://www.bkacontent.com/how-to-correctly-use-apa-style-title-case/>
-*   <https://en.wikipedia.org/wiki/AP_Stylebook>
-*   <https://en.wikipedia.org/wiki/APA_style>
-*   <http://blog.apastyle.org/apastyle/2012/03/title-case-and-sentence-case-capitalization-in-apa-style.html>
+## Contribute
+
+Yes please!
+See [How to Contribute to Open Source][contribute].
+
+## Security
+
+This package is safe.
 
 ## License
 
@@ -88,6 +159,14 @@ Convert a value (`string`) to title case (`string`) using [AP][]/[APA][] style.
 
 [npm]: https://docs.npmjs.com/cli/install
 
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[typescript]: https://www.typescriptlang.org
+
+[contribute]: https://opensource.guide/how-to-contribute/
+
 [license]: license
 
 [author]: http://zeke.sikelianos.com