github.com/googleapis/api-linter@v1.65.2/docs/rules/0192/has-comments.md (about)

     1  ---
     2  rule:
     3    aip: 192
     4    name: [core, '0192', has-comments]
     5    summary: Everything in a proto file must be commented.
     6  permalink: /192/has-comments
     7  redirect_from:
     8    - /0192/has-comments
     9  ---
    10  
    11  # Omnipresent comments
    12  
    13  This rule enforces that every descriptor in every proto file has a _public_
    14  leading comment, as mandated in [AIP-192][].
    15  
    16  ## Details
    17  
    18  This rule looks at each descriptor in each proto file (exempting oneofs and the
    19  file itself) and complains if no public comment is found _above_ the
    20  descriptor.
    21  
    22  ## Examples
    23  
    24  **Incorrect** code for this rule:
    25  
    26  ```proto
    27  // Incorrect.
    28  // A representation of a book.
    29  message Book {
    30    string name = 1;  // No leading comment.
    31  }
    32  ```
    33  
    34  **Correct** code for this rule:
    35  
    36  ```proto
    37  // Correct.
    38  // A representation of a book.
    39  message Book {
    40    // The resource name of the book.
    41    string name = 1;
    42  }
    43  ```
    44  
    45  ## Disabling
    46  
    47  If you need to violate this rule, use a leading comment above the descriptor
    48  (and revel in the irony). Remember to also include an [aip.dev/not-precedent][]
    49  comment explaining why.
    50  
    51  ```proto
    52  // A representation of a book.
    53  message Book {
    54    // (-- api-linter: core::0192::has-comments=disabled
    55    //     aip.dev/not-precedent: We need to do this because reasons. --)
    56    string name = 1;
    57  }
    58  ```
    59  
    60  [aip-192]: https://aip.dev/192
    61  [aip.dev/not-precedent]: https://aip.dev/not-precedent