From 00d257c35df6a455e15638b1d28b5f7a3b891ffa Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Tue, 1 Nov 2022 15:22:38 +0100 Subject: [PATCH] Add improved docs --- readme.md | 126 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 107 insertions(+), 19 deletions(-) diff --git a/readme.md b/readme.md index a12c8c6..c6ed6e9 100644 --- a/readme.md +++ b/readme.md @@ -8,19 +8,58 @@ Formula to detect the grade level of text according to the [gunning fog index][formula]. +## Contents + +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`gunningFog(counts)`](#gunningfogcounts) +* [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 algorithm is based on syllables, whereas some others are not, which means +it’s tougher to get right and slower to calculate. + See [`syllable`][syllable] for detecting syllables. ## Install -This package is ESM only: Node 12+ is needed to use it and it must be `import`ed -instead of `require`d. - -[npm][]: +This package is [ESM only][esm]. +In Node.js (version 14.14+, 16.0+), install with [npm][]: ```sh npm install gunning-fog ``` +In Deno with [`esm.sh`][esmsh]: + +```js +import {gunningFog} from 'https://esm.sh/gunning-fog@2' +``` + +In browsers with [`esm.sh`][esmsh]: + +```html + +``` + ## Use ```js @@ -31,40 +70,81 @@ import {gunningFog} from 'gunning-fog' // 1 sentence; 13 words; 4 polysillabic words, of which two are jargon, proper // nouns, or compound words. gunningFog({sentence: 1, word: 13, complexPolysillabicWord: 2}) -// => 11.353846... +// => 11.35384… ``` ## API -This package exports the following identifiers: `gunningFog`. +This package exports the identifier `gunningFog`. There is no default export. ### `gunningFog(counts)` -Given an object containing the number of words (`word`), the number of sentences -(`sentence`), and the number of complex (i.e., jargon, proper nouns, compound -words) polysillabic (three or more syllables) words -(`complexPolysillabicWord`) in a document, returns the grade level associated -with the document. +Given an object containing the number of words (`word`), the number of +sentences (`sentence`), and the number of complex (i.e., jargon, proper +nouns, compound words) polysillabic (three or more syllables) words +(`complexPolysillabicWord`) in a document, returns the grade level +associated with the document. + +##### `counts` + +Counts from input document. + +###### `counts.sentence` + +Number of sentences (`number`, required). + +###### `counts.word` + +Number of words (`number`, required). + +###### `counts.complexPolysillabicWord` + +Number of words that consist of three or more syllables, that are jargon, +proper nouns, or compound words (`number`, required). + +##### Returns + +Grade level associated with the document (`number`). + +## 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 * [`retext-readability`](https://github.com/wooorm/retext-readability) - — Complete readability measuring solution + — complete readability measuring solution * [`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`](https://github.com/words/flesch) - — Uses syllable count + — uses syllable count * [`flesch-kincaid`](https://github.com/words/flesch-kincaid) - — Like `flesch`; returns U.S. grade levels + — like `flesch`; returns U.S. grade levels * [`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 @@ -90,6 +170,14 @@ with the document. [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