> tibet-doclint

# tibet-doclint(1) -- validates method comment content

## SYNOPSIS

`tibet doclint [<target>] [--filter <filter>] [--missing] [--tap[=true|false]] [--no-tap] [--context=['app'|'lib'|'all']]`

## DESCRIPTION

Runs the `:doclint` command to validate method comment content.

The doclint command uses TIBET reflection to find all methods in your application that match an optional `<target>` and/or `--filter`. Matched methods then have their comment text checked for conformance to JSDoc3 and TIBET comment standards. This check can be a part of an overall quality pass which includes running `tibet lint` and `tibet test` on your code.

If you provide an optional string parameter it will be used as a target ID which must resolve via TP.bySystemId. Only methods owned by that target will be checked.

If you provide a `--filter` the method names themselves will be filtered to match only the pattern or string provided.

If you specify `--missing` only missing comments will be reported. No additional checks on content will be performed.

The context (app, lib, or all) is generally defaulted based on any target data given. For example, using a target of `APP.*` will cause an `app` context while using a target of `TP.*` will default to a lib context. To use the `all` context you must specify it explicitly.

By default output from this command follows the 'TAP' format. You can turn that off using `--tap=false` or `--no-tap`.

Note that because it uses method reflection, not file lists, to drive the checks when this command outputs file counts they represent the number of unique files containing matching methods, not a full list of project files. This can be disconcerting at first if you are used to listings which are built by file-driven tools.

## OPTIONS

- `target` : An optional target, usually a type name, to check.

- `--context` : Sets the context of the method scan which is run. The default is `app` which scans only application-level resources, ignoring any potential library resources. Other values are `lib` and `all`.

- `--filter` : An optional regular expression, expressed in /foo/ig form. This filter will be applied to fully-qualified method names.

- `--missing` : Optional flag which restricts lint warnings/errors to just missing comments.

- `--tap` : Optional flag to turn on/off TAP formatted output. The default is true.

## CONFIGURATION SETTINGS

No TIBET configuration variables are utilized by this command.

## ENVIRONMENT VARIABLES

No process environment variables are required by this command.

## EXAMPLES

### Checking a specific type for documentation lint

Assume a brand-new project. The application type won't have any methods yet so an initial test won't find any methods and hence will list no files:

    $ tibet doclint APP.hello.Application

    # Loading TIBET platform at 2019-11-09T17:43:17.668Z
    # TIBET reflection suite loaded and active in 5219ms
    # PASS: 0 errors in 0 of 0 files.

If we add a method but fail to add a proper comment we see different output:

    # Loading TIBET platform at 2019-11-09T17:43:17.668Z
    # TIBET reflection suite loaded and active in 5219ms
    not ok - ~app_src/APP.test1.Application.js
    # APP.test1.Application.TypeLocal.test (1) -> [missing comment]
    # FAIL: 1 errors in 1 of 1 files.

If we then comment our new method we'll see output to that effect:

    # Loading TIBET platform at 2019-11-09T17:43:17.668Z
    # TIBET reflection suite loaded and active in 5219ms
    ok - ~app_src/APP.test1.Application.js
    # PASS: 0 errors in 0 of 1 files.

### Checking your entire application for documentation lint

    $ tibet doclint

    # Loading TIBET platform at 2019-11-09T17:43:17.668Z
    # TIBET reflection suite loaded and active in 5219ms
    ok - ~app_src/APP.test1.Application.js
    ok - ~app_tags/APP.test1.app/APP.test1.app.js
    # PASS: 0 errors in 0 of 2 files.

### Checking a specific filtered set of targets for doclint

    $ tibet doclint --filter /app/

    # Loading TIBET platform at 2019-11-09T17:43:17.668Z
    # TIBET reflection suite loaded and active in 5219ms
    ok - ~app_tags/APP.test1.app/APP.test1.app.js
    # PASS: 0 errors in 0 of 1 files.

Note that you can also do case-insensitive filtering (with `i`) as follows:

    $ tibet doclint --filter /app/i

    # Loading TIBET platform at 2019-11-09T17:43:17.668Z
    # TIBET reflection suite loaded and active in 5219ms
    ok - ~app_src/APP.test1.Application.js
    ok - ~app_tags/APP.test1.app/APP.test1.app.js
    # PASS: 0 errors in 0 of 2 files.

## TIBET SHELL

This command invokes the client-side `:doclint` command, passing all flags and command line arguments to that command for processing.

## TROUBLESHOOTING

## SEE ALSO

- tibet-lint(1)