From 4b812e1b96a6b0d3d386026b0d0c73d95f9e60ac Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 30 Apr 2021 20:41:32 -0500 Subject: [PATCH] docs: Re-organize to clarify intent This is part of #237 --- README.md | 31 +++++++++++++++++--------- docs/{about.md => comparison.md} | 38 +++----------------------------- docs/design.md | 32 +++++++++++++++++++++++++++ docs/install.md | 11 --------- 4 files changed, 55 insertions(+), 57 deletions(-) rename docs/{about.md => comparison.md} (70%) create mode 100644 docs/design.md delete mode 100644 docs/install.md diff --git a/README.md b/README.md index bf39d71..27e1756 100644 --- a/README.md +++ b/README.md @@ -2,28 +2,37 @@ > **Source code spell checker** +Finds and corrects spelling mistakes among source code: +- Fast enough to run on monorepos +- Low false positives so you can run on PRs + [![Build Status](https://dev.azure.com/crate-ci/crate-ci/_apis/build/status/typos?branchName=master)](https://dev.azure.com/crate-ci/crate-ci/_build/latest?definitionId=11&branchName=master) [![codecov](https://codecov.io/gh/crate-ci/typos/branch/master/graph/badge.svg)](https://codecov.io/gh/crate-ci/typos) [![Documentation](https://img.shields.io/badge/docs-master-blue.svg)][Documentation] ![License](https://img.shields.io/crates/l/typos.svg) [![Crates Status](https://img.shields.io/crates/v/typos.svg)](https://crates.io/crates/typos) -## [About](docs/about.md) +Dual-licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE) -## [Install](docs/install.md) +## Documentation -## [Reference](docs/reference.md) +- [Installation](#install) +- [Reference](docs/reference.md) +- [Comparison with other spell checkers](docs/comparison.md) +- [Benchmarks](benchsuite/runs) +- [Design](docs/design.md) +- [Contribute](CONTRIBUTING.md) +- [CHANGELOG](CHANGELOG.md) -## [Contribute](CONTRIBUTING.md) +## Install -## License +[Download](https://github.com/crate-ci/typos/releases) a pre-built binary +(installable via [gh-install](https://github.com/crate-ci/gh-install). -Licensed under either of - - * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) - * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) - -at your option. +Or use rust to install: +```bash +cargo install typos-cli +``` [Crates.io]: https://crates.io/crates/typos-cli [Documentation]: https://docs.rs/typos diff --git a/docs/about.md b/docs/comparison.md similarity index 70% rename from docs/about.md rename to docs/comparison.md index 3a3eb21..63461b1 100644 --- a/docs/about.md +++ b/docs/comparison.md @@ -1,38 +1,4 @@ -# About `typos` - -## Design Requirements - -Spell checks source code: -- Requires special word-splitting logic to handle situations like hex (`0xDEADBEEF`), `c\nescapes`, `snake_case`, `CamelCase`, `SCREAMING_CASE`, and maybe `arrow-case`. -- Each programming language has its own quirks, like abbreviations, lack of word separator (`copysign`), etc -- Backwards compatibility might require keeping misspelled words. -- Case for proper nouns is irrelevant. - -Checking for errors in a CI: -- No false-positives. -- On spelling errors, sets the exit code to fail the CI. - -Quick feedback and resolution for developer: -- Fix errors for the user. -- Integration into other programs, like editors: - - `fork`: easy to call into and provides a stable API, including output format - - linking: either in the language of choice or bindings can be made to language of choice. - -## Design Trade Offs - -### typos uses a blacklist - -Blacklist: Known typos that map to their corresponding word -- Ignores unknown typos -- Ignores typos that follow c-escapes if they aren't handled correctly - -Whitelist: A confidence rating is given for how close a word is to one in the whitelist -- Sensitive to false positives due to hex numbers and c-escapes -- Traditional spell checkers use a whitelist. - -## Related Spell Checkers - -See also [benchmarks](../benchsuite/runs). +# Related Spell Checkers | | typos | [bloom42/misspell][misspell-rs] | [client9/misspell][misspell-go] | [codespell] | [scspell3k] | |----------------|-----------------------|---------------------------------|---------------------------------|-------------|-------------| @@ -53,6 +19,8 @@ See also [benchmarks](../benchsuite/runs). | API | Rust / [JSON Lines] | Rust | ? | Python | None | | License | MIT or Apache | AGPL | MIT | GPLv2 | GPLv2 | +See also [benchmarks](../benchsuite/runs). + [JSON Lines]: http://jsonlines.org/ [scspell3k]: https://github.com/myint/scspell [misspell-rs]: https://gitlab.com/bloom42/misspell diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 0000000..5d752fb --- /dev/null +++ b/docs/design.md @@ -0,0 +1,32 @@ +# Design + +## Requirements + +Spell checks source code: +- Requires special word-splitting logic to handle situations like hex (`0xDEADBEEF`), `c\nescapes`, `snake_case`, `CamelCase`, `SCREAMING_CASE`, and maybe `arrow-case`. +- Each programming language has its own quirks, like abbreviations, lack of word separator (`copysign`), etc +- Backwards compatibility might require keeping misspelled words. +- Case for proper nouns is irrelevant. + +Checking for errors in a CI: +- No false-positives. +- On spelling errors, sets the exit code to fail the CI. + +Quick feedback and resolution for developer: +- Fix errors for the user. +- Integration into other programs, like editors: + - `fork`: easy to call into and provides a stable API, including output format + - linking: either in the language of choice or bindings can be made to language of choice. + +## Trade Offs + +### typos uses a blacklist + +Blacklist: Known typos that map to their corresponding word +- Ignores unknown typos +- Ignores typos that follow c-escapes if they aren't handled correctly + +Whitelist: A confidence rating is given for how close a word is to one in the whitelist +- Sensitive to false positives due to hex numbers and c-escapes +- Traditional spell checkers use a whitelist. + diff --git a/docs/install.md b/docs/install.md deleted file mode 100644 index 70a6d5d..0000000 --- a/docs/install.md +++ /dev/null @@ -1,11 +0,0 @@ -# Install - - -[Download](https://github.com/crate-ci/typos/releases) a pre-built binary -(installable via [gh-install](https://github.com/crate-ci/gh-install). - -Or use rust to install: -```bash -cargo install typos-cli -``` -