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

     1  ---
     2  rule:
     3    aip: 192
     4    name: [core, '0192', deprecated-comment]
     5    summary: Deprecated elements must have a corresponding comment.
     6  permalink: /192/deprecated-comment
     7  redirect_from:
     8    - /0192/deprecated-comment
     9  ---
    10  
    11  # Deprecated comments
    12  
    13  This rule enforces that every element marked with the protobuf `deprecated`
    14  option has `"Deprecated: <reason>"` as the first line in the public leading
    15  comment, as mandated in [AIP-192][].
    16  
    17  ## Details
    18  
    19  This rule looks at each descriptor in each proto file, and complains if the
    20  protobuf `deprecated` option is set to `true`, but the first line of the public
    21  comment does not begin with "Deprecated: ".
    22  
    23  ## Examples
    24  
    25  **Incorrect** code for this rule:
    26  
    27  ```proto
    28  // A library service.
    29  service Library {
    30    // Incorrect.
    31    // Retrieves a book.
    32    rpc GetBook(GetBookRequest) returns (Book) {
    33      option deprecated = true;
    34    }
    35  }
    36  ```
    37  
    38  **Correct** code for this rule:
    39  
    40  ```proto
    41  // A library service.
    42  service Library {
    43    // Deprecated: Please borrow a physical book instead.
    44    // Correct.
    45    // Retrieves a book.
    46    rpc GetBook(GetBookRequest) returns (Book) {
    47      option deprecated = true;
    48    }
    49  }
    50  ```
    51  
    52  ## Disabling
    53  
    54  If you need to violate this rule, use a leading comment above the descriptor.
    55  Remember to also include an [aip.dev/not-precedent][] comment explaining why.
    56  
    57  ```proto
    58  // A library service.
    59  service Library {
    60    // (-- api-linter: core::0192::deprecated-comment=disabled
    61    //     aip.dev/not-precedent: We need to do this because reasons. --)
    62    // Incorrect.
    63    // Retrieves a book.
    64    rpc GetBook(GetBookRequest) returns (Book) {
    65      option deprecated = true;
    66    }
    67  }
    68  ```
    69  
    70  [aip-192]: https://aip.dev/192
    71  [aip.dev/not-precedent]: https://aip.dev/not-precedent