From bf7f1e38fb5254757e488f08eddc88eda5dee043 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Tue, 1 Nov 2022 14:16:25 +0100 Subject: [PATCH] Add improved docs --- index.js | 2 +- readme.md | 127 +++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 107 insertions(+), 22 deletions(-) diff --git a/index.js b/index.js index 31c50ee..fa5ecb5 100644 --- a/index.js +++ b/index.js @@ -26,7 +26,7 @@ const base = 206.835 * @param {Counts} counts * Counts from input document. * @returns {number} - * Result is 120 (every sentence consisting of only two one-syllable words) + * Result is `120` (every sentence consisting of only two one-syllable words) * or lower (including negative values). * * The values have the following semantics: diff --git a/readme.md b/readme.md index 4e18784..a9a2632 100644 --- a/readme.md +++ b/readme.md @@ -8,45 +8,102 @@ Formula to detect the grade level of text according to the [Flesch reading ease][formula]. -See [`syllable`][syllable] for detecting syllables. +## Contents -## Install +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`flesch(counts)`](#fleschcounts) +* [Types](#types) +* [Compatibility](#compatibility) +* [Related](#related) +* [Contribute](#contribute) +* [Security](#security) +* [License](#license) + +## What is this? + +This package exposes an algorithm to detect ease of reading of English texts. + +## When should I use this? + +You’re probably dealing with natural language, and know you need this, if +you’re here! -This package is ESM only: Node 12+ is needed to use it and it must be `import`ed -instead of `require`d. +This algorithm is based on syllables, whereas some others are not, which means +it’s tougher to get right and slower to calculate. -[npm][]: +See [syllable][] for detecting syllables. + +## Install + +This package is [ESM only][esm]. +In Node.js (version 14.14+, 16.0+), install with [npm][]: ```sh npm install flesch ``` +In Deno with [`esm.sh`][esmsh]: + +```js +import {flesch} from 'https://esm.sh/flesch@2' +``` + +In browsers with [`esm.sh`][esmsh]: + +```html + +``` + ## Use ```js import {flesch} from 'flesch' // For “The cat sat on the mat” (1 sentence, 6 words, 6 syllables). -flesch({sentence: 1, word: 6, syllable: 6}) // => 116.14500... +flesch({sentence: 1, word: 6, syllable: 6}) // => 116.14500… // For “The Australian platypus is seemingly a hybrid of mammal and reptilian // creature.” (1 sentence, 12 words, 23 syllables). -flesch({sentence: 1, word: 12, syllable: 23}) // => 32.50499... +flesch({sentence: 1, word: 12, syllable: 23}) // => 32.50499… ``` ## API -This package exports the following identifiers: `flesch`. +This package exports the identifier `flesch`. There is no default export. ### `flesch(counts)` -Given an object containing the number of words (`word`), the number of sentences -(`sentence`), and the number of syllables (`syllable`) in a document, returns -the reading ease associated with the document. +Given an object containing the number of words (`word`), the number of +sentences (`sentence`), and the number of syllables (`syllable`) in a +document, returns the reading ease associated with the document. + +##### `counts` + +Counts from input document. + +###### `counts.sentence` -Returned values are 120 (every sentence consisting of only two one-syllable -words), or lower (including negative values). +Number of sentences (`number`, required). + +###### `counts.word` + +Number of words (`number`, required). + +###### `counts.syllable` + +Number of syllables (`number`, required). + +##### Returns + +Result is `120` (every sentence consisting of only two one-syllable words) or +lower (including negative values). The values have the following semantics: @@ -60,25 +117,45 @@ Therefore we can use the following formula to approximate the average age a student would understand a document at, given score `score`: ```js -var age = 20 - Math.floor(score / 10) +const age = 20 - Math.floor(score / 10) ``` +## Types + +This package is fully typed with [TypeScript][]. +It exports the additional type `Counts`. + +## 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. + ## Related * [`automated-readability`](https://github.com/words/automated-readability) - — Uses character count instead of error-prone syllable parser + — uses character count instead of error-prone syllable parser * [`coleman-liau`](https://github.com/words/coleman-liau) - — Uses letter count instead of an error-prone syllable parser + — uses letter count instead of an error-prone syllable parser * [`dale-chall-formula`](https://github.com/words/dale-chall-formula) - — Uses a dictionary, suited for higher reading levels + — uses a dictionary, suited for higher reading levels * [`flesch-kincaid`](https://github.com/words/flesch-kincaid) - — Like `flesch`, returns U.S. grade levels + — like `flesch`, returns U.S. grade levels * [`gunning-fog`](https://github.com/words/gunning-fog) - — Uses syllable count, needs POS-tagging and NER + — uses syllable count, needs POS-tagging and NER * [`smog-formula`](https://github.com/words/smog-formula) - — Like `gunning-fog-index`, without needing advanced NLP + — like `gunning-fog-index`, without needing advanced NLP * [`spache-formula`](https://github.com/words/spache-formula) - — Uses a dictionary, suited for lower reading levels + — uses a dictionary, suited for lower reading levels + +## Contribute + +Yes please! +See [How to Contribute to Open Source][contribute]. + +## Security + +This package is safe. ## License @@ -104,6 +181,14 @@ var age = 20 - Math.floor(score / 10) [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]: https://wooorm.com