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

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