Add README.md

README.md

@@ -0,0 +1,67 @@
+# 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.