# field-comment-defined

Source: https://api-genie.dev/docs/linter/protobuf/rules/field-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: All at error.

This rule checks whether every field 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 `field-comment-defined` rule checks every field, including the fields of oneofs, map fields
and extension fields, and reports `Field '<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.

Turn the rule off if the fields of your files are documented elsewhere, or if their names are
descriptive enough. To exempt the fields of a single message, add an `// apigenie-lint-disable
field-comment-defined` comment to the message.

## Examples

**Good**.

```proto
syntax = "proto3";

package acme.pets.v1;

// A pet that lives in the shelter.
message Pet {
  // The name the shelter gave to the pet.
  string name = 1;
  // Free-form labels, such as the color of the pet.
  map<string, string> labels = 2;
}
```

**Bad**. The linter reports `Field 'labels' has no leading comment`.

```proto
syntax = "proto3";

package acme.pets.v1;

// A pet that lives in the shelter.
message Pet {
  // The name the shelter gave to the pet.
  string name = 1;
  map<string, string> labels = 2; // Free-form labels.
}
```
