enum-comment-defined
Since 0.9.0 · In the rulesets: Strict at error, All at error
This rule checks whether every enum 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 enum-comment-defined rule checks every enum, including enums nested in messages, and
reports Enum '<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 part of the strict and all rulesets.
Turn the rule off if the enums of your files are documented elsewhere, or if their names are
descriptive enough. Lines with an apigenie-lint-disable directive do not count as documentation: a
leading comment made only of directives does not satisfy the rule.
Examples
Good.
syntax = "proto3";
package acme.pets.v1;
// The species of a pet.
enum PetKind {
PET_KIND_UNSPECIFIED = 0;
PET_KIND_DOG = 1;
}
Bad. The linter reports Enum 'PetKind' has no leading comment.
syntax = "proto3";
package acme.pets.v1;
enum PetKind {
PET_KIND_UNSPECIFIED = 0;
PET_KIND_DOG = 1;
}
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:
enum-comment-defined: off