tag-description-defined

Since 0.0.1 · In the rulesets: Recommended at warning, Strict at warning, All at warning

This rule checks that every tag has a description of at least 10 characters that is not a placeholder.

Rule details

Tags are the sections of the documentation and the classes of a generated client; the description is the sentence at the top of the section that says what the group is for. A tag named Users with no description is a heading over a list.

The rule reports Tag '...' has no meaningful description defined when the description is missing, shorter than the minimum, white space only, or one of TBD, TODO and FIXME.

Configuration

A positive integer: the minimal length of a description. 10 by default.

Configuration example. Descriptions of at least 20 characters.

commands:
  lint:
    rules:
      tag-description-defined:
        - warning
        - 20

Examples

Good.

tags:
  - name: User
    description: Operations on user accounts.
  - name: Product
    description: Operations on the product catalog.

Bad. An empty description and a missing one.

tags:
  - name: User
    description: ""
  - name: Product

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.

commands:
  lint:
    rules:
      tag-description-defined: off
Was this helpful?