# 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 full version information
              --short-version         show just the version number
  -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
  -t[STRING]  --todo-marker[=STRING]  override the default TODO marker with a custom string
  -A FILE     --annotations=FILE      load automatic annotation rules
```

### 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.

### Insert annotations automatically

In case you have violations that always result in the same annotation over and
over again, you can supply one or more files that contain automatic decisions.

Each line may be one of the following:

```
Intentional (Rule "autosar_cpp14_a18_9_1") "reason why it's intentional"
FalsePositive (Rule "autosar_cpp14_a18_9_1") "reason why it's a false-positive"
ToDo (Rule "autosar_cpp14_a18_9_1")
```

Lines may be disabled by prefixing them with `#` or `--`.