github.com/googleapis/api-linter@v1.65.2/docs/rules/0216/nesting.md (about)

     1  ---
     2  rule:
     3    aip: 216
     4    name: [core, '0216', nesting]
     5    summary: Lifecycle state enums should be nested within the resource.
     6  permalink: /216/nesting
     7  redirect_from:
     8    - /0216/nesting
     9  ---
    10  
    11  # States
    12  
    13  This rule enforces that all lifecycle state enums are nested within their
    14  resource, as recommended in [AIP-216][].
    15  
    16  ## Details
    17  
    18  This rule iterates over enumerations and looks for enums with a name of
    19  `FooState` where a corresponding `Foo` message exists in the same file. If it
    20  finds such a case, it recommends that the enum be nested within the message.
    21  
    22  ## Examples
    23  
    24  **Incorrect** code for this rule:
    25  
    26  ```proto
    27  // Incorrect.
    28  message Book {
    29    BookState book_state = 1;
    30  }
    31  
    32  // Should be nested under `Book`.
    33  enum BookState {
    34    BOOK_STATE_UNSPECIFIED = 0;
    35  }
    36  ```
    37  
    38  **Correct** code for this rule:
    39  
    40  ```proto
    41  // Correct.
    42  message Book {
    43    enum State {
    44      STATE_UNSPECIFIED = 0;
    45    }
    46    State state = 1;
    47  }
    48  ```
    49  
    50  ## Disabling
    51  
    52  If you need to violate this rule, use a leading comment above the enum.
    53  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    54  
    55  ```proto
    56  message Book {
    57    BookState book_state = 1;
    58  }
    59  
    60  // (-- api-linter: core::0216::nesting=disabled
    61  //     aip.dev/not-precedent: We need to do this because reasons. --)
    62  enum BookState {
    63    BOOK_STATE_UNSPECIFIED = 0;
    64  }
    65  ```
    66  
    67  If you need to violate this rule for an entire file, place the comment at the
    68  top of the file.
    69  
    70  [aip-216]: https://aip.dev/216
    71  [aip.dev/not-precedent]: https://aip.dev/not-precedent