From 4f85e39e098c705a42949c1e113a3b1d4ae307d6 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Wed, 26 Jun 2019 21:46:14 -0600 Subject: [PATCH] docs: Comparison with other tools Fixes #12 --- README.md | 2 ++ docs/about.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 docs/about.md diff --git a/README.md b/README.md index 6fde785..ac4b8bc 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ ![License](https://img.shields.io/crates/l/defenestrate.svg) [![Crates Status](https://img.shields.io/crates/v/defenestrate.svg)](https://crates.io/crates/defenestrate) +## [About](docs/about.md) + ## Install For now, `rust` is required for install: diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..b286473 --- /dev/null +++ b/docs/about.md @@ -0,0 +1,58 @@ +# About defenestrate + +## 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 + +### defenestrate 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 + +| | defenestrate | [scspell3k] | [bloom42/misspell][misspell-rs] | [client9/misspell][misspell-go] | +|---------------|----------------------|-------------|---------------------------------|---------------------------------| +| "Runtime" | Rust ([#18][def-18] | Python | Rust | None | +| Dictionary | Blacklist | Whitelist | Blacklist | Blacklist | +| Custom Dict | No ([#9][def-9] | Yes | No | ? | +| Per-Lang Dict | No ([#14][def-14] | Yes | No | ? | +| CamelCase | Yes | Yes | No | ? | +| snake_case | Yes | Yes | No | ? | +| Ignore Hex | No ([#19][def-19] | Yes | No | ? | +| C-Escapes | No ([#20][def-3] | Yes | No | ? | +| Encodings | UTF-8 ([#17][def-17] | Auto | UTF-8 | ? | +| API | Rust / [JSON Lines] | None | Rust | ? | +| License | MIT | Apache | GPLv2 | AGPL | MIT | + +[JSON Lines]: http://jsonlines.org/ +[scspell3k]: https://github.com/myint/scspell +[misspell-rs]: https://gitlab.com/bloom42/misspell +[misspell-go]: https://github.com/client9/misspell +[def-9]: https://github.com/epage/defenestrate/issues/9 +[def-14]: https://github.com/epage/defenestrate/issues/14 +[def-17]: https://github.com/epage/defenestrate/issues/17 +[def-18]: https://github.com/epage/defenestrate/issues/18 +[def-19]: https://github.com/epage/defenestrate/issues/19 +[def-3]: https://github.com/epage/defenestrate/issues/3