service-comment-defined

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error

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

Turn the rule off if the services 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;

// Manages the pets of the shelter.
service PetService {
  rpc GetPet(GetPetRequest) returns (GetPetResponse);
}

message GetPetRequest {
  string name = 1;
}

message GetPetResponse {
  string name = 1;
}

Bad. The linter reports Service 'PetService' has no leading comment.

syntax = "proto3";

package acme.pets.v1;

service PetService {
  rpc GetPet(GetPetRequest) returns (GetPetResponse);
}

message GetPetRequest {
  string name = 1;
}

message GetPetResponse {
  string name = 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:
        service-comment-defined: off

Related rules

Was this helpful?