The rule to check if all public declarations (variables, procedures, etc.) have documentation comments The syntax in a configuration file is::
[ruleType] ?not? hasDoc [entityType] [templateFile]
- ruleType is the type of rule which will be executed. Proper values are: check, search, count and fix. For more information about the types of rules, please refer to the program's documentation. Check type will raise an error if there is a public declaration which doesn't have documentation. Search type will list all public declarations which have documentation and raise error if nothing was found. Count type will simply list the amount of public declarations which have documentation. Fix type with negation will remove all documentation from the selected type of the code entities. Without negation, it will add a template of documentation from the selected text file into the configured type of code entities.
- optional word not means negation for the rule. Adding word not will change to inform only about public declaration which have documentation. Probably useable only with search and count type of rule.
- entityType is the type of entity which will be looking for. Proper values
are:
all
: check everything what can have documentation but without fields of objects' declarations,callables
: check all declarations of subprograms (procedures, functions, macros, etc.),types
: check declarations of types,typesFields
: check declarations of objects' fields,modules
: check only module for documentation. - templateFile is parameter required only by fix type of hasDoc rule. Other types of the rule can skip it. It should contain the template of documentation which will be inserted into the checked code. The documentation should be in reStructuredText format without leading sign for Nim documentation. It will be inserted in all desired types of entities.
Disabling the rule
It is possible to disable the rule for a selected part of the checked code
by using pragma ruleOff: "hasDoc" in the element from which the rule
should be disabled. For example, if the rule should be disabled for procedure
proc main()
, the full declaration of it should be:
proc main () {.ruleOff: "hasDoc".}
To enable the rule again, the pragma ruleOn: "hasDoc" should be added in
the element which should be checked. For example, if the rule should be
re-enabled for const a = 1
, the full declaration should be:
const a = 1 {.ruleOn: "hasDoc".}
Examples
Check if all public declarations in module have documentation:
check hasDoc all
Search for all modules which don't have documentation:
search not hasDoc modules