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