# Annotator - an interactive TM2/TM3 annotation tool

This tool lets you interactively annotate your code given a =defects.err= file.

## Installation

Get the most recent release, unpack it and add the binary to your PATH.

## How to use it

After a /Coverity™/ run, you end up with a =defects.err= and would like to
annotate your code accordingly. In order to do so, just execute the =annotator=:

```
annotator
```

This will by default use the =defects.err= file in the current directory and
scan it for violations. It will then ask you what to do with each violation - by
default only /Newest/ violations will be handled, but this can be overridden
with a command-line switch.

After all violations have been treated, you'll end up with a bunch of =*.fix=
files next to each source file - those are the annotated source files - you may
run diff on them to check if they look fine or just move them over your original
source file.

### Possible annotations

The annotator is able to generate three kinds of annotations:

  - *Intentional* - by pressing `i`, this will annotate with `coverity[rule] <reason>`
  - *False-Positive* - by pressing `f`, this will annotate with `coverity[rule : FALSE] <reason>`
  - *Todo* - by pressing `t`, this will annotate with a FIXME marker

## Advanced usage scenarios

The current annotator supports the following command-line arguments:

```
$ annotator --help
Usage: annotator [OPTIONS] files...

A tool to semi-automatically add Coverity source-code annotations based on found defects.


  -v       --verbose           be more verbose, pass multiple times to increase verbosity
  -i       --inplace           replace source-file after inserting annotations
  -V       --version           show version
           --short-version     show version
  -h       --help              show usage information
  -a       --all               handle all defects not just Newest
  -C[NUM]  --context[=NUM]     specify how much context should be shown around a violation
```

### In-place annotations

The `annotator` allows to annotate in-place, i.e. it will automatically rename
the `.fix` file after you are done with all violations within that file. This
can be achieved by passing `-i` or `--inplace`.

### Process all violations

By default the annotator will only handle *Newest* violations and not those that
are already contained within the Coverity database for some reason. However,
it's still possible to process all found violations by passing `-a` or `--all`
on the command-line.