oneof-comment-defined (Protobuf linter rule)

oneof-comment-defined

Since 0.9.0

This rule checks whether every oneof 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 oneof-comment-defined rule checks every oneof, and reports Oneof '<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.

Configuration

This rule has no options.

Examples

Good.

syntax = "proto3";

package acme.pets.v1;

// A pet that lives in the shelter.
message Pet {
  string name = 1;
  // How the shelter can reach the owner.
  oneof contact {
    string email = 2;
    string phone = 3;
  }
}

Bad. The linter reports Oneof 'contact' has no leading comment.

syntax = "proto3";

package acme.pets.v1;

// A pet that lives in the shelter.
message Pet {
  string name = 1;
  oneof contact {
    string email = 2;
    string phone = 3;
  }
}

When Not to Use It

You may disable this rule if the oneofs of your files are documented elsewhere, or if their names are descriptive enough. To exempt the oneofs of a single message, add an // apigenie-lint-disable oneof-comment-defined comment to the message.

Compatibility