enum-value-comment-defined

Since 0.9.0 · In the rulesets: All at error

This rule checks whether every enum value 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-value-comment-defined rule checks every enum value, and reports Enum value '<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 values of your files are documented elsewhere, or if their names are descriptive enough. To exempt the values of a single enum, add an // apigenie-lint-disable enum-value-comment-defined comment to the enum.

Examples

Good.

syntax = "proto3";

package acme.pets.v1;

// The species of a pet.
enum PetKind {
  // The species is not known.
  PET_KIND_UNSPECIFIED = 0;
  // A dog.
  PET_KIND_DOG = 1;
}

Bad. The linter reports Enum value 'PET_KIND_DOG' has no leading comment.

syntax = "proto3";

package acme.pets.v1;

// The species of a pet.
enum PetKind {
  // The species is not known.
  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-value-comment-defined: off

Related rules

Last updated on View as Markdown
Was this helpful?