AEP-0192 Linter Rules

Absolute links

This rule attempts to enforce that every descriptor in every proto file uses absolute links, as mandated in AEP-192.

Details

This rule looks at each descriptor in each proto file (exempting oneofs and the file itself) and tries to find Markdown links using the [link](uri) syntax, and complains if the URI does not have :// in it.

Examples

Incorrect code for this rule:

// Incorrect.
// A representation of [a book](/wiki/Book).
message Book {
  string name = 1;
}

Correct code for this rule:

// Correct.
// A representation of [a book](https://en.wikipedia.org/wiki/Book).
message Book {
  string name = 1;
}

Disabling

If you need to violate this rule, use a leading comment above the descriptor (and revel in the irony). Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0192::absolute-links=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
// A representation of [a book](/wiki/Book).
message Book {
  string name = 1;
}

Deprecated comments

This rule enforces that every element marked with the protobuf deprecated option has "Deprecated: <reason>" as the first line in the public leading comment, as mandated in AEP-192.

Details

This rule looks at each descriptor in each proto file, and complains if the protobuf deprecated option is set to true, but the first line of the public comment does not begin with “Deprecated: “.

Examples

Incorrect code for this rule:

// A library service.
service Library {
  // Incorrect.
  // Retrieves a book.
  rpc GetBook(GetBookRequest) returns (Book) {
    option deprecated = true;
  }
}

Correct code for this rule:

// A library service.
service Library {
  // Deprecated: Please borrow a physical book instead.
  // Correct.
  // Retrieves a book.
  rpc GetBook(GetBookRequest) returns (Book) {
    option deprecated = true;
  }
}

Disabling

If you need to violate this rule, use a leading comment above the descriptor. Remember to also include an aep.dev/not-precedent comment explaining why.

// A library service.
service Library {
  // (-- api-linter: core::0192::deprecated-comment=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  // Incorrect.
  // Retrieves a book.
  rpc GetBook(GetBookRequest) returns (Book) {
    option deprecated = true;
  }
}

Omnipresent comments

This rule enforces that every descriptor in every proto file has a public leading comment, as mandated in AEP-192.

Details

This rule looks at each descriptor in each proto file (exempting oneofs and the file itself) and complains if no public comment is found above the descriptor.

Examples

Incorrect code for this rule:

// Incorrect.
// A representation of a book.
message Book {
  string name = 1;  // No leading comment.
}

Correct code for this rule:

// Correct.
// A representation of a book.
message Book {
  // The resource name of the book.
  string name = 1;
}

Disabling

If you need to violate this rule, use a leading comment above the descriptor (and revel in the irony). Remember to also include an aep.dev/not-precedent comment explaining why.

// A representation of a book.
message Book {
  // (-- api-linter: core::0192::has-comments=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string name = 1;
}

No HTML in comments

This rule enforces that every descriptor in every proto file does not use raw HTML in comments, as mandated in AEP-192.

Details

This rule looks at each descriptor in each proto file (exempting oneofs and the file itself) and tries to find HTML tags, and complains if it finds any.

Note: This lint rule uses a regular expression to look for HTML, which is a famous anti-pattern. We do it anyway to avoid taking a large dependency for one rule. Therefore, this rule allows many false negatives to avoid any false positives; that is, it will intentionally let more complex HTML through in order to prevent cases where it complains and is wrong.

Examples

Incorrect code for this rule:

// Incorrect.
// A representation of a book.
message Book {
  // (-- This comment should use Markdown, not HTML.) --)
  // The name of the book.
  // Format: <code>publishers/{publisher}/books/{book}</code>
  string name = 1;
}

Correct code for this rule:

// Correct.
// A representation of a book.
message Book {
  // The name of the book.
  // Format: `publishers/{publisher}/books/{book}`
  string name = 1;
}

Disabling

If you need to violate this rule, use a leading comment above the descriptor (and revel in the irony). Remember to also include an aep.dev/not-precedent comment explaining why.

// A representation of a book.
message Book {
  // (-- api-linter: core::0192::no-html=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  // The name of the book.
  // Format: <code>publishers/{publisher}/books/{book}</code>
  string name = 1;
}

No Markdown headings

This rule enforces that public comments for proto descriptors do not have Markdown headings (#, ##, etc.), as mandated in AEP-192.

Details

This rule looks at each descriptor in each proto file (exempting oneofs and the file itself) and complains if public comments include Markdown headings (that become <h1>, <h2>, etc.).

Examples

Incorrect code for this rule:

// Incorrect.
// # A representation of a book.
message Book {
  // ## The resource name of the book.
  string name = 1;
}

Correct code for this rule:

// Correct.
// A representation of a book.
message Book {
  // The resource name of the book.
  string name = 1;
}

Disabling

If you need to violate this rule, use a leading comment above the descriptor. Remember to also include an aep.dev/not-precedent comment explaining why.

// # A representation of a book.
// (-- api-linter: core::0192::no-markdown-headings=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  // # The resource name of the book.
  // (-- api-linter: core::0192::no-markdown-headings=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  string name = 1;
}

No Markdown tables

This rule enforces that public comments for proto descriptors do not have Markdown tables, as mandated in AEP-192.

Details

This rule looks at each descriptor in each proto file (exempting oneofs and the file itself) and complains if public comments include Markdown tables.

Examples

Incorrect code for this rule:

// Incorrect.
// Fields on the book include:
//
// Name     | Type
// -------- | --------
// `name`   | `string`
// `author` | `string`
message Book {
  // The resource name of the book.
  string name = 1;
}

Correct code for this rule:

// Correct.
// Fields on the book include:
//
// - `name`: `string`
// - `author`: `string`
message Book {
  // The resource name of the book.
  string name = 1;
}

Disabling

If you need to violate this rule, use a leading comment above the descriptor. Remember to also include an aep.dev/not-precedent comment explaining why.

// Fields on the book include:
//
// Name     | Type
// -------- | --------
// `name`   | `string`
// `author` | `string`
// (-- api-linter: core::0192::no-markdown-tables=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  // The resource name of the book.
  string name = 1;
}

Only leading comments

This rule enforces that every descriptor in every proto file has a public comment information only in leading comment (not trailing comments or detached comments), as mandated in AEP-192.

Details

This rule looks at each descriptor in each proto file (exempting oneofs and the file itself) and complains if public comments are either trailing or detached. Internal comments are not considered.

Examples

Incorrect code for this rule:

// Incorrect.
// BEGIN LIBRARY SECTION  <-- detached comment; shows up in docs.

// A representation of a book.
message Book {
  // The resource name of the book.
  string name = 1;
}

Correct code for this rule:

// Correct.
// (-- BEGIN LIBRARY SECTION --)

// A representation of a book.
message Book {
  // The resource name of the book.
  string name = 1;
}

Disabling

If you need to violate this rule, use a leading comment above the descriptor (and revel in the irony). Remember to also include an aep.dev/not-precedent comment explaining why.

// BEGIN LIBRARY SECTION  <-- detached comment; shows up in docs.

// A representation of a book.
// (-- api-linter: core::0192::only-leading-comments=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  // The resource name of the book.
  string name = 1;
}