field-comment-defined
Since 0.9.0 · In the rulesets: All at error
This rule checks whether every field of a Protobuf file has a leading comment.
Rule details
Comments are the documentation of a Protobuf API: protoc passes them to the code generators,
which copy them to the generated code, and documentation generators render them.
The field-comment-defined rule checks every field, including the fields of oneofs, map fields
and extension fields, and reports Field '<name>' has no leading comment when there is no
leading comment, or when it contains only whitespace. A leading comment is the comment right
before the declaration, as protoc attaches it: a comment separated from the declaration by a
blank line is a detached comment, and a comment after the declaration on the same line is a
trailing comment; neither counts. Both // and /* */ comments count.
The rule is only part of the all ruleset.
Turn the rule off if the fields of your files are documented elsewhere, or if their names are
descriptive enough. To exempt the fields of a single message, add an // apigenie-lint-disable field-comment-defined comment to the message.
Examples
Good.
syntax = "proto3";
package acme.pets.v1;
// A pet that lives in the shelter.
message Pet {
// The name the shelter gave to the pet.
string name = 1;
// Free-form labels, such as the color of the pet.
map<string, string> labels = 2;
}
Bad. The linter reports Field 'labels' has no leading comment.
syntax = "proto3";
package acme.pets.v1;
// A pet that lives in the shelter.
message Pet {
// The name the shelter gave to the pet.
string name = 1;
map<string, string> labels = 2; // Free-form labels.
}
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:
field-comment-defined: off