From 737ff6afe3dd6f1876fef7eae3d03c7c0779703a Mon Sep 17 00:00:00 2001 From: Alexander Kobjolke Date: Fri, 6 Jan 2023 14:20:31 +0100 Subject: [PATCH] doc: Replace README.md by README.org --- Makefile | 20 ++++++++----- README.md | 84 ------------------------------------------------------ README.org | 68 +++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 78 insertions(+), 94 deletions(-) delete mode 100644 README.md diff --git a/Makefile b/Makefile index d2dd2b8..b656f16 100644 --- a/Makefile +++ b/Makefile @@ -1,22 +1,27 @@ -.PHONY: default all install watch clean build release distclean lint +.PHONY: default all install watch clean build release distclean lint doc default: all all: build -build: builddir build/bin/annotator - GHCFLAGS = -iapp -isrc -Wall -O2 -outputdir build/.obj BUILDDIR = build DESTDIR = ~/.local BINDIR = ${DESTDIR}/bin DOCDIR = ${DESTDIR}/share/doc/annotator +build: builddir | $(BUILDDIR)/bin/annotator doc + builddir: - mkdir -p $(BUILDDIR)/bin $(BUILDDIR)/.obj $(BUILDDIR)/ci $(BUILDDIR)/dist + mkdir -p $(BUILDDIR)/{bin,.obj,ci,dist,doc} + +doc: builddir | $(BUILDDIR)/doc/README.md $(BUILDDIR)/bin/annotator: app/Main.hs src/*.hs ghc --make $(GHCFLAGS) $< -o $@ +$(BUILDDIR)/doc/README.md: README.org + pandoc -t gfm $< -o $@ + watch: @git ls-files src app Makefile | entr make -s build install @@ -31,9 +36,10 @@ clean: distclean: clean @rm -rf dist -install: $(BUILDDIR)/bin/annotator - @install -m 0755 -D -t ${BINDIR} $< - @install -m 0644 -D -t ${DOCDIR} README.md +install: build + @install -m 0755 -D -t ${BINDIR} $(BUILDDIR)/bin/annotator + @install -m 0644 -D -t ${DOCDIR} README.org + @install -m 0644 -D -t ${DOCDIR} $(BUILDDIR)/doc/README.md release: script/make-release @$< diff --git a/README.md b/README.md deleted file mode 100644 index bae8d08..0000000 --- a/README.md +++ /dev/null @@ -1,84 +0,0 @@ -# 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] ` - - *False-Positive* - by pressing `f`, this will annotate with `coverity[rule : FALSE] ` - - *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 `--`. diff --git a/README.org b/README.org index 3e55f92..591bada 100644 --- a/README.org +++ b/README.org @@ -1,14 +1,54 @@ -#+title: Readme +#+title: Annotator - an interactive Coverity annotation tool + +* Abstract + +This tool lets you interactively annotate your code given a =defects.err= file. The file should contain file and line information along with the Coverity rule that was violated. An example may look like this: + +#+begin_example csv +main.cpp:162:INFO: Newest, autosar_cpp14_a20_8_6_violation: Object "std::unique_ptr >(read_configuration(uri))" is not constructed using "std::make_shared". +#+end_example * Installation +Get the most recent release, unpack it and add the binary to your PATH. + * Usage -#+begin_src sh :results output +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=: + +#+begin_src sh +annotator +#+end_src + +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] = +- FalsePositive :: by pressing =f=, this will annotate with =coverity[rule : FALSE] = +- Todo :: by pressing =t=, this will annotate with a TODO marker + +* Advanced usage scenarios + +The current annotator supports the following command-line arguments: + +#+name: annotator-help +#+begin_src sh :results output :exports both annotator --help #+end_src -#+RESULTS: +#+RESULTS: annotator-help #+begin_example Usage: annotator [OPTIONS] files... @@ -32,3 +72,25 @@ A tool to semi-automatically add Coverity source-code annotations based on found # a comment -- another comment #+end_example + +** 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: + +#+begin_example haskell +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") +#+end_example + +Lines may be disabled by prefixing them with =#= or =--=.