From 12f45871b2c52f8285df749e0c6a4141bf6ec88c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Fri, 7 Dec 2018 14:41:20 +0100
Subject: Document code coverage

---
 doc/src/guide/coverage.asciidoc | 60 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 58 insertions(+), 2 deletions(-)

(limited to 'doc/src/guide/coverage.asciidoc')

diff --git a/doc/src/guide/coverage.asciidoc b/doc/src/guide/coverage.asciidoc
index f33f878..02f8b5b 100644
--- a/doc/src/guide/coverage.asciidoc
+++ b/doc/src/guide/coverage.asciidoc
@@ -1,6 +1,62 @@
 [[coverage]]
 == Code coverage
 
-// @todo Write it.
+Erlang.mk provides support for code coverage via the tool
+`cover` that comes with Erlang/OTP. Code coverage lets you
+see what parts of your code are covered by the tests.
 
-Placeholder chapter.
+=== Enabling cover when running tests
+
+To run tests with code coverage enabled, simply define
+`COVER=1` either on the command line or in your Makefile:
+
+[source,bash]
+$ make tests COVER=1
+
+When running the targets `tests` or `check` the code
+coverage report will be built automatically. This is
+not the case for test framework specific targets,
+however. In those cases you can generate the reports
+manually:
+
+[source,bash]
+$ make eunit proper COVER=1
+$ make cover-report
+
+Note that Common Test has some support for `cover`
+built-in and that it will generate code coverage
+reports in the Common Test logs regardless. The
+report that Erlang.mk generates is however common
+to all test frameworks and might be more useful.
+
+=== Adding applications to the cover report
+
+By default Erlang.mk will include all the applications
+in the code coverage report, except external dependencies.
+
+To include some dependencies in the report, you can
+define the `COVER_DEPS` variable:
+
+[source,make]
+COVER_DEPS = cowlib
+
+When using multi application repositories you can exclude
+some applications by defining the `COVER_APPS` variable:
+
+[source,make]
+COVER_APPS = presence backend
+
+=== Configuring paths
+
+By default Erlang.mk will store 'coverdata' files and
+code coverage reports under the 'cover/' directory. The
+variables `COVER_DATA_DIR` and `COVER_REPORT_DIR` can be
+set to use a different location.
+
+=== Merging coverdata files
+
+The target `all.coverdata` will take all existing
+'coverdata' files and merge them into one:
+
+[source,bash]
+$ make all.coverdata
-- 
cgit v1.2.3