# rpc-comment-defined

Source: https://api-genie.dev/docs/linter/protobuf/rules/rpc-comment-defined

A rule of the Protobuf linter, which reads proto3 files; the reader rejects proto2 and editions files. 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**.

```proto
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`.

```proto
syntax = "proto3";

package acme.pets.v1;

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

message GetPetRequest {
  string name = 1;
}

message GetPetResponse {
  string name = 1;
}
```
