spell-check
Since 0.9.0 · In the rulesets: Strict at warning, All at warning
This rule checks the spelling of the comments of a Protobuf file.
Rule details
Comments are the documentation of a Protobuf API: code generators copy them to the generated
code, and documentation generators render them. The rule reports every misspelled word, with up
to three suggested corrections, for example
Misspelled word 'nmae' in comment (did you mean 'name', 'nae', 'mae'?), or
Misspelled word '<word>' in comment when there is no suggestion.
The rule checks the leading, trailing and detached comments of every declaration of the file:
the syntax statement (including a license header before it), the package, imports and options,
messages, fields, oneofs, enums, enum values, services and RPCs. The issue points at the
declaration the comment is attached to. Comments inside a statement, such as
int32 /* type */ count = 1;, are not checked.
Comments are read as CommonMark: the rule checks their prose, and skips code spans, code blocks, raw HTML and link destinations. The rule also skips the tokens which are not plain words:
- URLs, e-mail addresses, paths, and file and domain names (
pet.proto,example.com), - identifiers:
snake_case,camelCaseand names with inner capitals (PetService), - acronyms, also in the plural (
RPC,APIs,ID's), - tokens with digits (
v1,404) and single letters.
The spell checker is a C++ port of Hunspell. By default it uses
the built-in English (US) dictionary from SCOWL (as shipped with
LibreOffice), extended with words common in API descriptions, such as webhook, endpoint,
namespace, nullable and json. Any Hunspell dictionary can be used instead.
The rule is part of the strict and all rulesets.
Turn the rule off if your comments are written in a language you have no dictionary for. To accept
the names of your products and other domain terms, add them to the words option rather than
disabling the rule.
Configuration
This rule accepts an object with the following options:
words: extra words to accept, for example product names. A word is accepted as given, capitalized and in capitals:petstoreacceptspetstore,PetstoreandPETSTORE.dictionaryandaffix: paths of a Hunspell dictionary (.dic) and its affix file (.aff) to use instead of the built-in dictionary. They go together. Dictionaries in UTF-8, ISO-8859-1, ISO-8859-2 and ISO-8859-15 are supported.suggestions: how many corrections to suggest for a word, from 0 to 10 (default 3). Suggestions are the costly part of the rule; on large files with many unknown words,0makes it much faster.
Configuration example
version: "1.0"
commands:
lint:
protobuf:
rules:
spell-check:
- warning
- words: [petstore]
dictionary: path/to/en_GB.dic
affix: path/to/en_GB.aff
Examples
Good.
syntax = "proto3";
package acme.pets.v1;
// A pet that lives in the shelter.
message Pet {
// The name of the pet.
string name = 1; // Must not be empty.
}
Bad. The linter reports, both at the name field,
Misspelled word 'nmae' in comment (did you mean 'name', 'nae', 'mae'?) and
Misspelled word 'emtpy' in comment (did you mean 'empty', 'mtpy'?).
syntax = "proto3";
package acme.pets.v1;
// A pet that lives in the shelter.
message Pet {
// The nmae of the pet.
string name = 1; // Must not be emtpy.
}
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.protobuf has the details.
commands:
lint:
protobuf:
rules:
spell-check: off