are-docs-informative
Advanced tools
Comparing version
@@ -1,46 +0,8 @@ | ||
interface InformativeDocsOptions { | ||
/** | ||
* Words that can be considered synonyms (aliases) of each other. | ||
* | ||
* @default | ||
* ```json | ||
* { | ||
* "a": ["an", "our"] | ||
* } | ||
* ``` | ||
* | ||
* @example | ||
* With `{ aliases: { emoji: ["smiley", "winkey"] } }`, | ||
* the following comment would be considered uninformative: | ||
* ```js | ||
* /** Default smiley/winkey. *\/ | ||
* export const defaultSmiley = "🙂"; | ||
* ``` | ||
*/ | ||
aliases?: Record<string, string[]>; | ||
/** | ||
* Words that are ignored when searching for one that adds meaning. | ||
* | ||
* @default | ||
* ```json | ||
* ["a", "an", "i", "in", "of", "s", "the"] | ||
* ``` | ||
* | ||
* @example | ||
* With `{ uselessWords: ["our"] }`, the following comment would | ||
* be considered uninformative: | ||
* ```js | ||
* /** Our text. *\/ | ||
* export const text = ":)"; | ||
* ``` | ||
*/ | ||
uselessWords?: string[]; | ||
} | ||
import { InformativeDocsOptions } from './types.js'; | ||
/** | ||
* @param docs - Any amount of docs text, such as from a JSDoc description. | ||
* @param name - Name of the entity the docs text is describing. | ||
* @param options - Additional options to customize informativity checking. | ||
* @param docs Any amount of docs text, such as from a JSDoc description. | ||
* @param name Name of the entity the docs text is describing. | ||
* @param options Additional options to customize informativity checking. | ||
* @returns Whether the docs include at least one word with new information. | ||
* | ||
* @example | ||
@@ -55,4 +17,4 @@ * ```js | ||
*/ | ||
declare function areDocsInformative(docs: string | string[], name: string | string[], { aliases, uselessWords, }?: InformativeDocsOptions): boolean; | ||
declare function areDocsInformative(docs: string | string[], name: string | string[], options?: InformativeDocsOptions): boolean; | ||
export { InformativeDocsOptions, areDocsInformative }; |
@@ -1,10 +0,8 @@ | ||
// src/index.ts | ||
var defaultAliases = { | ||
export * from "./types.js"; | ||
const defaultAliases = { | ||
a: ["an", "our"] | ||
}; | ||
var defaultUselessWords = ["a", "an", "i", "in", "of", "s", "the"]; | ||
function areDocsInformative(docs, name, { | ||
aliases = defaultAliases, | ||
uselessWords = defaultUselessWords | ||
} = {}) { | ||
const defaultUselessWords = ["a", "an", "i", "in", "of", "re", "s", "the"]; | ||
function areDocsInformative(docs, name, options = {}) { | ||
const { aliases = defaultAliases, uselessWords = defaultUselessWords } = options; | ||
const docsWords = new Set(splitTextIntoWords(docs)); | ||
@@ -11,0 +9,0 @@ const nameWords = splitTextIntoWords(name); |
123
package.json
{ | ||
"name": "are-docs-informative", | ||
"version": "0.0.2", | ||
"description": "Checks whether a documentation description introduces any new information.", | ||
"version": "0.1.0", | ||
"description": "Checks whether a documentation description introduces any new information. ℹ️", | ||
"repository": { | ||
"type": "git", | ||
"url": "https://github.com/JoshuaKGoldberg/are-docs-informative" | ||
"url": "git+https://github.com/JoshuaKGoldberg/are-docs-informative.git" | ||
}, | ||
"license": "MIT", | ||
"author": "Josh Goldberg <npm@joshuakgoldberg.com>", | ||
"author": { | ||
"name": "JoshuaKGoldberg", | ||
"email": "npm@joshuakgoldberg.com" | ||
}, | ||
"type": "module", | ||
"exports": { | ||
".": { | ||
"types": { | ||
"import": "./lib/index.d.ts", | ||
"require": "./lib/index.d.cts" | ||
}, | ||
"import": "./lib/index.js", | ||
"require": "./lib/index.cjs" | ||
} | ||
}, | ||
"main": "./lib/index.js", | ||
"main": "lib/index.js", | ||
"files": [ | ||
"LICENSE.md", | ||
"README.md", | ||
"lib/", | ||
"package.json", | ||
"LICENSE.md", | ||
"README.md" | ||
"package.json" | ||
], | ||
"scripts": { | ||
"build": "tsc", | ||
"build:full": "tsup src/index.ts --clean --format cjs,esm --outDir lib --dts && cp lib/index.d.ts lib/index.d.cts", | ||
"format": "prettier \"**/*\" --ignore-unknown", | ||
"format:write": "pnpm format --write", | ||
"lint": "eslint . --max-warnings 0 --report-unused-disable-directives", | ||
"build": "tsup", | ||
"format": "prettier .", | ||
"lint": "eslint . --max-warnings 0", | ||
"lint:knip": "knip", | ||
"lint:md": "markdownlint \"**/*.md\" \".github/**/*.md\" --rules sentences-per-line", | ||
"lint:package": "npmPkgJsonLint .", | ||
"lint:packages": "pnpm-deduplicate --list", | ||
"lint:packages": "pnpm dedupe --check", | ||
"lint:spelling": "cspell \"**\" \".github/**/*\"", | ||
"prepare": "husky install", | ||
"should-semantic-release": "should-semantic-release --verbose", | ||
"test": "vitest" | ||
"prepare": "husky", | ||
"test": "vitest", | ||
"tsc": "tsc" | ||
}, | ||
@@ -48,43 +38,44 @@ "lint-staged": { | ||
"devDependencies": { | ||
"@types/eslint": "^8.21.1", | ||
"@typescript-eslint/eslint-plugin": "^5.48.2", | ||
"@typescript-eslint/parser": "^5.48.2", | ||
"@vitest/coverage-istanbul": "^0.29.0", | ||
"cspell": "^6.19.2", | ||
"eslint": "^8.32.0", | ||
"eslint-config-prettier": "^8.6.0", | ||
"eslint-plugin-deprecation": "^1.3.3", | ||
"eslint-plugin-eslint-comments": "^3.2.0", | ||
"eslint-plugin-import": "^2.27.5", | ||
"eslint-plugin-jsonc": "^2.6.0", | ||
"eslint-plugin-markdown": "^3.0.0", | ||
"eslint-plugin-no-only-tests": "^3.1.0", | ||
"eslint-plugin-regexp": "^1.12.0", | ||
"eslint-plugin-simple-import-sort": "^10.0.0", | ||
"eslint-plugin-typescript-sort-keys": "^2.1.0", | ||
"eslint-plugin-vitest": "^0.1.0", | ||
"eslint-plugin-yml": "^1.5.0", | ||
"husky": "^8.0.3", | ||
"jsonc-eslint-parser": "^2.1.0", | ||
"knip": "2.8.2", | ||
"lint-staged": "^13.1.0", | ||
"markdownlint": "^0.27.0", | ||
"markdownlint-cli": "^0.33.0", | ||
"npm-package-json-lint": "^6.4.0", | ||
"npm-package-json-lint-config-default": "^5.0.0", | ||
"pnpm-deduplicate": "^0.4.1", | ||
"prettier": "^2.8.3", | ||
"prettier-plugin-packagejson": "^2.4.2", | ||
"release-it": "^15.6.0", | ||
"sentences-per-line": "^0.2.1", | ||
"should-semantic-release": "^0.1.0", | ||
"tsup": "^6.7.0", | ||
"typescript": "^5.0.0", | ||
"vitest": "^0.29.0", | ||
"yaml-eslint-parser": "^1.2.0" | ||
"@eslint-community/eslint-plugin-eslint-comments": "4.4.1", | ||
"@eslint/js": "9.24.0", | ||
"@release-it/conventional-changelog": "10.0.0", | ||
"@types/eslint-plugin-markdown": "2.0.2", | ||
"@types/node": "22.14.0", | ||
"@vitest/coverage-v8": "3.1.1", | ||
"@vitest/eslint-plugin": "1.1.38", | ||
"console-fail-test": "0.5.0", | ||
"create-typescript-app": "2.34.0", | ||
"cspell": "8.18.0", | ||
"eslint": "9.24.0", | ||
"eslint-plugin-jsdoc": "50.6.8", | ||
"eslint-plugin-jsonc": "2.20.0", | ||
"eslint-plugin-markdown": "5.1.0", | ||
"eslint-plugin-n": "17.16.2", | ||
"eslint-plugin-package-json": "0.29.0", | ||
"eslint-plugin-perfectionist": "4.11.0", | ||
"eslint-plugin-regexp": "2.7.0", | ||
"eslint-plugin-yml": "1.17.0", | ||
"husky": "9.1.7", | ||
"knip": "5.50.1", | ||
"lint-staged": "15.5.0", | ||
"markdownlint": "0.37.4", | ||
"markdownlint-cli": "0.44.0", | ||
"prettier": "3.5.3", | ||
"prettier-plugin-curly": "0.3.1", | ||
"prettier-plugin-packagejson": "2.5.10", | ||
"prettier-plugin-sh": "0.17.0", | ||
"release-it": "18.1.2", | ||
"sentences-per-line": "0.3.0", | ||
"tsup": "8.4.0", | ||
"typescript": "5.8.2", | ||
"typescript-eslint": "8.29.0", | ||
"vitest": "3.1.1" | ||
}, | ||
"packageManager": "pnpm@7.31.0", | ||
"packageManager": "pnpm@10.8.0", | ||
"engines": { | ||
"node": ">=14" | ||
"node": ">=18" | ||
}, | ||
"publishConfig": { | ||
"provenance": true | ||
} | ||
} |
<h1 align="center">Are Docs Informative</h1> | ||
<p align="center">Checks whether a documentation description introduces any new information.</p> | ||
<p align="center"> | ||
Checks whether a documentation description introduces any new information. | ||
ℹ️ | ||
</p> | ||
<p align="center"> | ||
<a href="#contributors" target="_blank"> | ||
<!-- prettier-ignore-start --> | ||
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --> | ||
<img alt="All Contributors: 1" src="https://img.shields.io/badge/all_contributors-1-21bb42.svg" /> | ||
<!-- prettier-ignore-start --> | ||
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --> | ||
<a href="#contributors" target="_blank"><img alt="👪 All Contributors: 1" src="https://img.shields.io/badge/%F0%9F%91%AA_all_contributors-1-21bb42.svg" /></a> | ||
<!-- ALL-CONTRIBUTORS-BADGE:END --> | ||
<!-- prettier-ignore-end --> | ||
</a> | ||
<a href="https://codecov.io/gh/JoshuaKGoldberg/are-docs-informative" target="_blank"> | ||
<img alt="Codecov Test Coverage" src="https://codecov.io/gh/JoshuaKGoldberg/are-docs-informative/branch/main/graph/badge.svg?token=eVIFY4MhfQ"/> | ||
</a> | ||
<a href="https://github.com/JoshuaKGoldberg/are-docs-informative/blob/main/.github/CODE_OF_CONDUCT.md" target="_blank"> | ||
<img alt="Contributor Covenant" src="https://img.shields.io/badge/code_of_conduct-enforced-21bb42" /> | ||
</a> | ||
<a href="https://github.com/JoshuaKGoldberg/are-docs-informative/blob/main/LICENSE.md" target="_blank"> | ||
<img alt="License: MIT" src="https://img.shields.io/github/license/JoshuaKGoldberg/are-docs-informative?color=21bb42"> | ||
</a> | ||
<a href="https://github.com/sponsors/JoshuaKGoldberg" target="_blank"> | ||
<img alt="Sponsor: On GitHub" src="https://img.shields.io/badge/sponsor-on_github-21bb42.svg" /> | ||
</a> | ||
<img alt="Style: Prettier" src="https://img.shields.io/badge/style-prettier-21bb42.svg" /> | ||
<img alt="TypeScript: Strict" src="https://img.shields.io/badge/typescript-strict-21bb42.svg" /> | ||
<!-- prettier-ignore-end --> | ||
<a href="https://github.com/JoshuaKGoldberg/are-docs-informative/blob/main/.github/CODE_OF_CONDUCT.md" target="_blank"><img alt="🤝 Code of Conduct: Kept" src="https://img.shields.io/badge/%F0%9F%A4%9D_code_of_conduct-kept-21bb42" /></a> | ||
<a href="https://codecov.io/gh/JoshuaKGoldberg/are-docs-informative" target="_blank"><img alt="🧪 Coverage" src="https://img.shields.io/codecov/c/github/JoshuaKGoldberg/are-docs-informative?label=%F0%9F%A7%AA%20coverage" /></a> | ||
<a href="https://github.com/JoshuaKGoldberg/are-docs-informative/blob/main/LICENSE.md" target="_blank"><img alt="📝 License: MIT" src="https://img.shields.io/badge/%F0%9F%93%9D_license-MIT-21bb42.svg" /></a> | ||
<a href="http://npmjs.com/package/are-docs-informative" target="_blank"><img alt="📦 npm version" src="https://img.shields.io/npm/v/are-docs-informative?color=21bb42&label=%F0%9F%93%A6%20npm" /></a> | ||
<img alt="💪 TypeScript: Strict" src="https://img.shields.io/badge/%F0%9F%92%AA_typescript-strict-21bb42.svg" /> | ||
</p> | ||
@@ -31,2 +23,4 @@ | ||
> See this in action in [`jsdoc/informative-docs`](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/informative-docs.md)! | ||
```shell | ||
@@ -45,3 +39,4 @@ npm i are-docs-informative | ||
The `areDocsInformative` function can receive a third, optional parameter | ||
The `areDocsInformative` function can receive a third, optional object parameter. | ||
It can contain any of the following properties. | ||
@@ -54,3 +49,3 @@ #### `aliases` | ||
```js | ||
```ts | ||
/** Default smiley/winkey. */ | ||
@@ -74,3 +69,3 @@ export const defaultSmiley = "🙂"; | ||
```js | ||
```ts | ||
/** Our text. */ | ||
@@ -89,3 +84,3 @@ export const text = ":)"; | ||
See [`.github/CONTRIBUTING.md`](./.github/CONTRIBUTING.md), then [`.github/DEVELOPMENT.md`](./.github/DEVELOPMENT.md). | ||
Thanks! 💖 | ||
Thanks! ℹ | ||
@@ -101,3 +96,3 @@ ## Contributors | ||
<tr> | ||
<td align="center" valign="top" width="14.28%"><a href="http://www.joshuakgoldberg.com"><img src="https://avatars.githubusercontent.com/u/3335181?v=4?s=100" width="100px;" alt="Josh Goldberg"/><br /><sub><b>Josh Goldberg</b></sub></a><br /><a href="#tool-JoshuaKGoldberg" title="Tools">🔧</a></td> | ||
<td align="center" valign="top" width="14.28%"><a href="http://www.joshuakgoldberg.com"><img src="https://avatars.githubusercontent.com/u/3335181?v=4?s=100" width="100px;" alt="Josh Goldberg"/><br /><sub><b>Josh Goldberg</b></sub></a><br /><a href="#tool-JoshuaKGoldberg" title="Tools">🔧</a> <a href="https://github.com/JoshuaKGoldberg/are-docs-informative/commits?author=JoshuaKGoldberg" title="Documentation">📖</a> <a href="#infra-JoshuaKGoldberg" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="https://github.com/JoshuaKGoldberg/are-docs-informative/commits?author=JoshuaKGoldberg" title="Code">💻</a> <a href="#content-JoshuaKGoldberg" title="Content">🖋</a> <a href="#ideas-JoshuaKGoldberg" title="Ideas, Planning, & Feedback">🤔</a> <a href="#maintenance-JoshuaKGoldberg" title="Maintenance">🚧</a> <a href="#projectManagement-JoshuaKGoldberg" title="Project Management">📆</a></td> | ||
</tr> | ||
@@ -113,4 +108,2 @@ </tbody> | ||
<!-- You can remove this notice if you don't want it 🙂 no worries! --> | ||
> 💙 This package is based on [@JoshuaKGoldberg](https://github.com/JoshuaKGoldberg)'s [template-typescript-node-package](https://github.com/JoshuaKGoldberg/template-typescript-node-package). | ||
> 💝 This package was templated with [`create-typescript-app`](https://github.com/JoshuaKGoldberg/create-typescript-app) using the [Bingo engine](https://create.bingo). |
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
34
-5.56%10232
-24.91%81
-42.55%103
-6.36%1
Infinity%