JAL-3541 docs for enabling OpenClover coverage reports and adjustable build parameter...

diff --git a/doc/building.md b/doc/building.md
index c2d40a4..badb593 100644 (file)
--- a/doc/building.md
+++ b/doc/building.md
@@ -541,5 +541,35 @@ perl -n -e 'm/^\s*<(\w+)[^>]*\bmediaFileName=/ && print "$1\n";' utils/install4j
 in the `jalview` root folder.
 
 
+## Enabling Code Coverage with OpenClover
+
+Bytecode instrumentation tasks are enabled by specifying 'true' (or just a non-whitespace non-numeric word) in the 'clover' property. This adds the 'openclover' plugin to the build script's classpath, making it possible to track code execution during test which can be viewed as an HTML report published at build/reports/clover/index.html.
+
+```gradle -Pclover=true test cloverReport```
+
+#### Troubleshooting report generation
+
+The build forks a new JVM process to run the clover report generation tools (both XML and HTML reports are generated by default). The following properties can be used to specify additional options or adjust JVM memory settings. Default values for these options are:
+
+##### JVM Memory settings - increase if out of memory errors are reported
+
+```cloverReportJVMHeap = 2g```
+
+##### -Dfile.encoding=UTF-8 is an essential parameters for report generation. Add additional ones separated by a space.
+
+```cloverReportJVMArgs = -Dfile.encoding=UTF-8```
+
+##### Add -v to debug velocity html generation errors, or -d to track more detailed issues with the coverage database
+
+```cloverReportHTMLOptions = ```
+
+##### -v for verbose, -d for debug level messages (as above)
+
+```cloverReportXMLOptions = ```
+
+
+_Note_ do not forget to include the -Dfile.encoding=UTF-8 option: this is essential for some platforms in order for Clover to correctly parse some Jalview source files that contain characters that are UTF-8 encoded. 
+
+
 ---
 [Jalview Development Team](mailto:help@jalview.org)