rpc-comment-defined
Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error
This rule checks whether every RPC 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 rpc-comment-defined rule checks every RPC of every service, and reports RPC '<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 RPCs of your files are documented elsewhere, or if their names are
descriptive enough. To exempt the RPCs of a single service, add an // apigenie-lint-disable rpc-comment-defined comment to the service.
Examples
Good.
syntax = "proto3";
package acme.pets.v1;
service PetService {
// Returns the pet with the given name.
rpc GetPet(GetPetRequest) returns (GetPetResponse);
}
message GetPetRequest {
string name = 1;
}
message GetPetResponse {
string name = 1;
}
Bad. The linter reports RPC 'GetPet' 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:
rpc-comment-defined: off