enum-comment-defined (Protobuf linter rule)

enum-comment-defined

Since 0.9.0

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.

Configuration

This rule has no options.

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;
}

When Not to Use It

You may disable this rule 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.

Compatibility