SONAR-14343 Improve documentation on coverage

3 files changed, 209 insertions, 51 deletions

diff --git a/server/sonar-docs/src/pages/analysis/coverage.md b/server/sonar-docs/src/pages/analysis/coverage.md
index 3123e145dfa..a119420db04 100644
--- a/server/sonar-docs/src/pages/analysis/coverage.md
+++ b/server/sonar-docs/src/pages/analysis/coverage.md
@@ -3,13 +3,34 @@ title: Test Coverage & Execution
 url: /analysis/coverage/
 ---
 
-This page lists analysis parameters related to test coverage and execution reports. For more other parameters, see [Analysis Parameters](/analysis/analysis-parameters/).
+Test coverage reports and test execution reports are important code quality metrics that you can import into SonarQube. Test coverage reports tell you the percentage of your code that is covered by your test cases. Test execution reports tell you which tests have been run and their results.
 
-SonarQube doesn't run your tests or generate reports. It only imports pre-generated reports. Below you'll find language- and tool-specific analysis parameters for importing coverage and execution reports.
+[[info]]
+| SonarQube doesn't run your tests or generate reports. To include coverage results in your analysis, you need to set up a third-party coverage tool to generate reports and configure SonarQube to import those reports. 
 
-In the [Guides](https://community.sonarsource.com/c/announce/guides) category of the [SonarSource Community forum](https://community.sonarsource.com/) you might find instructions on generating these reports.
+Below you'll find guidelines and resources as well as well as language- and tool-specific analysis parameters for importing coverage and execution reports.
 
-Some properties support the following wildcards in paths. The remarks for properties that support wildcards will mention that fact. If the remarks do not say wildcards are supported, then they are not.:
+## General Guidlines
+Before importing test coverage and execution reports, you need to have the appropriate [SonarScanner](/analysis/overview/) configured as part of your build pipeline. Then, complete the following steps:
+
+1. Set up your coverage tool to run as part of your build pipeline. Your coverage tool should be set up to run *before* the SonarScanner analysis.
+1. Configure the coverage tool so that location and format of the output report files matches what the SonarScanner expects.
+1. Configure the analysis parameters of the SonarScanner so that it can import the report files.
+
+Now, on each build of your project, your coverage tool performs its analysis and outputs its results to one or more files (usually one for test coverage and one for test execution). Then, the SonarScanner imports those files and sends the results to SonarQube as part of its analysis process.
+
+## Supported report formats
+SonarQube supports a variety of formats from third-party tools. We also provide a [generic test data format](/analysis/generic-test/) to easily gather and import test coverage and execution information into SonarQube.
+
+## Language-specific guides
+On the [SonarSource Community forum](https://community.sonarsource.com/), you can find guides with instructions on generating reports for the following languages:
+* [Apex, C/C++, Objective-C, Go, JS/TS, and Python](https://community.sonarsource.com/t/coverage-test-data-generate-reports-for-apex-c-c-objective-c-go-js-ts-and-python/)
+* [Swift](https://community.sonarsource.com/t/coverage-test-data-generate-reports-for-swift/)
+* [C#, VB.net](https://community.sonarsource.com/t/coverage-test-data-generate-reports-for-c-vb-net/)
+* [JaCoCo](https://community.sonarsource.com/t/coverage-test-data-importing-jacoco-coverage-report-in-xml-format/)
+
+## Wildcards
+Some analysis parameters support the following path wildcards. Properties that support wildcards are noted in the **Description** columns of the analysis parameter tables below:
 
 Symbol|Meaning
 ---|---
@@ -17,55 +38,169 @@ Symbol|Meaning
 `*`|any number of characters
 `**`|any number of directories
 
-## Test Coverage
+## Test coverage analysis parameters
 Unless otherwise specified, these properties require values that are relative to project root.
 
-Language|Property|Remarks
-----|----|----
-**Any**|`sonar.coverageReportPaths`|Path to coverage report in the [Generic Test Data](/analysis/generic-test/) format.
-Apex|`sonar.apex.coverage.reportPath`|Path to the `test-result-codecoverage.json` report file generated by the [`apex:test:run`](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_force_apex.htm?search_text=apex%20test#cli_reference_test_run) command of the [Salesforce CLI](https://developer.salesforce.com/tools/sfdxcli). Note, you must have a [Salesforce DX project](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_workspace_setup.htm) set up and linked to your Org
-C / C++ / Objective-C|`sonar.cfamily.gcov.reportsPath`|Path to the directory containing native `*.gcov` reports (not the XML reports generated by gcovr)
-C / C++ / Objective-C|`sonar.cfamily.llvm-cov.reportPath`| Path to a llvm-cov report
-C / C++ / Objective-C|`sonar.cfamily.vscoveragexml.reportsPath`|Path may be absolute or relative to the solution directory. Path wildcards (see above) are supported. Note that the `.coveragexml` report format offered by Visual Studio is not supported.
-C / C++ / Objective-C|`sonar.cfamily.bullseye.reportPath`| Path to the report from Bullseye, version >= 8.9.63 (use [covxml](http://www.bullseye.com/help/ref-covxml.html) tool)
-C#|`sonar.cs.vscoveragexml.reportsPaths`|Path to Visual Studio Code Coverage report. Multiple paths may be comma-delimited, or included via wildcards. See _Notes on importing .NET reports_ below.
-C#|`sonar.cs.dotcover.reportsPaths`|Path to dotCover coverage report. See _Notes on importing .NET reports_ below.
-C#|`sonar.cs.opencover.reportsPaths`|Path to OpenCover coverage report. See _Notes on importing .NET reports_ below.
-C#|`sonar.cs.ncover3.reportsPaths`![](/images/cross.svg)|**Deprecated.** Path to NCover3 coverage report. See _Notes on importing .NET reports_ below.
-Flex|`sonar.flex.cobertura.reportPaths`|Path to the Cobertura XML reports. Multiple paths may be comma-delimited. May be absolute or relative to the project base directory.
-Go|`sonar.go.coverage.reportPaths`|Comma-delimited list of paths to coverage report files. Path wildcards are supported (see above) since SonarGo 1.1.
-Java / Kotlin / Scala / JVM|`sonar.coverage.jacoco.xmlReportPaths`|Path to JaCoCo XML coverage reports. Path wildcards are supported (see above).
-JavaScript / TypeScript|`sonar.javascript.lcov.reportPaths`|Comma-delimited list of paths to LCOV coverage report files. Paths may be absolute or relative to project root.
-PHP|`sonar.php.coverage.reportPaths`|Comma-delimited list of paths to Clover XML-format coverage report files. Paths may be absolute or relative to project root.
-Python|`sonar.python.coverage.reportPaths`|Comma-delimited list of paths to coverage reports in the Cobertura XML format. Path wildcards are supported (see above). Leave unset to use the default (`coverage-reports/*coverage-*.xml`).
-Ruby|`sonar.ruby.coverage.reportPaths`|Comma-delimited list of paths to SimpleCov report files generated with the [JSON formatter](https://github.com/simplecov-ruby/simplecov#json-formatter) (availaible from SimpleCov 0.20). For SimpleCov versions < 0.18, you can provide `.resultset.json` report files (not recommended). Paths may be absolute or relative to project-root.
-Scala|`sonar.scala.coverage.reportPaths`|Comma-separated list of paths to `scoverage.xml` report files generaged by Scoverage.
-Swift, Xcode 9.3+|&nbsp;|You can use the [xccov-to-sonarqube-generic.sh](https://github.com/SonarSource/sonar-scanning-examples/blob/master/swift-coverage/swift-coverage-example/xccov-to-sonarqube-generic.sh) script from the [sonar-scanning-examples/swift-coverage](https://github.com/SonarSource/sonar-scanning-examples/tree/master/swift-coverage) project convert output from Xcode 9.3's xccov tool to the [Generic Test Data](/analysis/generic-test/) format.
-Swift, Xcode 7-9.2|`sonar.swift.coverage.reportPath`|Path to the report generated by `llvm-cov show`. Path may be absolute or relative to project root.
-VB.NET|`sonar.vbnet.vscoveragexml.reportsPaths`|Path to Visual Studio Code Coverage report. Multiple paths may be comma-delimited, or included via wildcards. See _Notes on importing .NET reports_ below.
-VB.NET|`sonar.vbnet.dotcover.reportsPaths`|Path to dotCover coverage report. See _Notes on importing .NET reports_ below.
-VB.NET|`sonar.vbnet.opencover.reportsPaths`|Path to OpenCover coverage report. See _Notes on importing .NET reports_ below.
-VB.Net|`sonar.vbnet.ncover3.reportsPaths`![](/images/cross.svg)|**Deprecated.** Path to NCover3 coverage report. See _Notes on importing .NET reports_ below.
-
-
-## Test Execution
+### All Languages
+
+Analysis parameter|Description
+----|----
+`sonar.coverageReportPaths`|Path to coverage report in the [Generic Test Data](/analysis/generic-test/) format.
+
+### Apex
+
+Analysis parameter|Description
+----|----
+`sonar.apex.coverage.reportPath`|Path to the `test-result-codecoverage.json` report file generated by the [`apex:test:run`](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_force_apex.htm?search_text=apex%20test#cli_reference_test_run) command of the [Salesforce CLI](https://developer.salesforce.com/tools/sfdxcli). Note, you must have a [Salesforce DX project](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_workspace_setup.htm) set up and linked to your Org
+
+### C/C++/Objective-C
+
+Analysis parameter|Description
+----|----
+`sonar.cfamily.gcov.reportsPath`|Path to the directory containing native `*.gcov` reports (not the XML reports generated by gcovr)
+`sonar.cfamily.llvm-cov.reportPath`| Path to a llvm-cov report
+`sonar.cfamily.vscoveragexml.reportsPath`|Path may be absolute or relative to the solution directory. Path wildcards (see above) are supported. Note that the `.coveragexml` report format offered by Visual Studio is not supported.
+`sonar.cfamily.bullseye.reportPath`| Path to the report from Bullseye, version >= 8.9.63 (use [covxml](http://www.bullseye.com/help/ref-covxml.html) tool)
+
+### C&#x23;
+
+Analysis parameter|Description
+----|----
+`sonar.cs.vscoveragexml.reportsPaths`|Path to Visual Studio Code Coverage report. Multiple paths may be comma-delimited, or included via wildcards. See _Notes on importing .NET reports_ below.
+`sonar.cs.dotcover.reportsPaths`|Path to dotCover coverage report. See _Notes on importing .NET reports_ below.
+`sonar.cs.opencover.reportsPaths`|Path to OpenCover coverage report. See _Notes on importing .NET reports_ below.
+`sonar.cs.ncover3.reportsPaths`![](/images/cross.svg)|**Deprecated.** Path to NCover3 coverage report. See _Notes on importing .NET reports_ below.
+
+### Flex
+
+Analysis parameter|Description
+----|----
+`sonar.flex.cobertura.reportPaths`|Path to the Cobertura XML reports. Multiple paths may be comma-delimited. May be absolute or relative to the project base directory.
+
+### Go
+
+Analysis parameter|Description
+----|----
+`sonar.go.coverage.reportPaths`|Comma-delimited list of paths to coverage report files. Path wildcards are supported (see above) since SonarGo 1.1.
+
+### Java, Kotlin, Scala, and JVM
+
+Analysis parameter|Description
+----|----
+`sonar.coverage.jacoco.xmlReportPaths`|Path to JaCoCo XML coverage reports. Path wildcards are supported (see above).
+
+### Javascript and Typescript
+
+Analysis parameter|Description
+----|----
+`sonar.javascript.lcov.reportPaths`|Comma-delimited list of paths to LCOV coverage report files. Paths may be absolute or relative to project root.
+
+### PHP
+
+Analysis parameter|Description
+----|----
+`sonar.php.coverage.reportPaths`|Comma-delimited list of paths to Clover XML-format coverage report files. Paths may be absolute or relative to project root.
+
+### Python
+
+Analysis parameter|Description
+----|----
+`sonar.python.coverage.reportPaths`|Comma-delimited list of paths to coverage reports in the Cobertura XML format. Path wildcards are supported (see above). Leave unset to use the default (`coverage-reports/*coverage-*.xml`).
+
+### Ruby
+
+Analysis parameter|Description
+----|----
+`sonar.ruby.coverage.reportPaths`|Comma-delimited list of paths to SimpleCov report files generated with the [JSON formatter](https://github.com/simplecov-ruby/simplecov#json-formatter) (availaible from SimpleCov 0.20). For SimpleCov versions < 0.18, you can provide `.resultset.json` report files (not recommended). Paths may be absolute or relative to project-root.
+
+### Scala
+
+Analysis parameter|Description
+----|----
+`sonar.scala.coverage.reportPaths`|Comma-separated list of paths to `scoverage.xml` report files generaged by Scoverage.
+
+### Swift, Xcode 9.3+
+
+Analysis parameter|Description
+----|----
+&nbsp;|You can use the [xccov-to-sonarqube-generic.sh](https://github.com/SonarSource/sonar-scanning-examples/blob/master/swift-coverage/swift-coverage-example/xccov-to-sonarqube-generic.sh) script from the [sonar-scanning-examples/swift-coverage](https://github.com/SonarSource/sonar-scanning-examples/tree/master/swift-coverage) project convert output from Xcode 9.3's xccov tool to the [Generic Test Data](/analysis/generic-test/) format.
+
+### Swift, Xcode 7–9.2
+
+Analysis parameter|Description
+----|----
+`sonar.swift.coverage.reportPath`|Path to the report generated by `llvm-cov show`. Path may be absolute or relative to project root.
+
+### VB.NET
+
+Analysis parameter|Description
+----|----
+`sonar.vbnet.vscoveragexml.reportsPaths`|Path to Visual Studio Code Coverage report. Multiple paths may be comma-delimited, or included via wildcards. See _Notes on importing .NET reports_ below.
+`sonar.vbnet.dotcover.reportsPaths`|Path to dotCover coverage report. See _Notes on importing .NET reports_ below.
+`sonar.vbnet.opencover.reportsPaths`|Path to OpenCover coverage report. See _Notes on importing .NET reports_ below.
+`sonar.vbnet.ncover3.reportsPaths`![](/images/cross.svg)|**Deprecated.** Path to NCover3 coverage report. See _Notes on importing .NET reports_ below.
+
+
+## Test execution analysis parameters
 Unless otherwise specified, these properties require values that are relative to project root.
 
-Language|Property|Remarks
----|---|---
-**All**|`sonar.testExecutionReportPaths`|Comma-delimited list of paths to execution reports in the [Generic Execution Data](/analysis/generic-test/) format. The paths must be relative to the project's base directory (root module).
-C / C++ / Objective-C|`sonar.cfamily.cppunit.reportsPath`|Path to the directory holding the [CPPUnit](http://sourceforge.net/projects/cppunit/) reports. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
-C#|`sonar.cs.vstest.reportsPaths`|Paths to VSTest reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
-C#|`sonar.cs.nunit.reportsPaths`|Paths to NUnit execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
-C#|`sonar.cs.xunit.reportsPaths`|Paths to xUnit execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
-Go|`sonar.go.tests.reportPaths`|Comma-delimited list of paths to unit test report files. Paths may be absolute or relative to project root.
-Java / Kotlin|`sonar.junit.reportPaths`|Comma-delimited list of paths to Surefire XML-format reports.
-JavaScript / TypeScript |&nbsp;|You can use [jest-sonar-reporter](https://www.npmjs.com/package/jest-sonar-reporter) or [karma-sonarqube-unit-reporter](https://github.com/tornaia/karma-sonarqube-unit-reporter) to create reports in the [Generic Execution Data](/analysis/generic-test/) format. Both packages are available on npm.
-PHP|`sonar.php.tests.reportPath`|Path to the PHPUnit unit test execution report file. Path may be absolute or relative to project root.
-Python|`sonar.python.xunit.reportPath`|Path to unit test execution report. Leave unset to use the default (`xunit-reports/xunit-result-*.xml`). Path wildcards (see above) are supported. If any paths in the report are invalid, set `sonar.python.xunit.skipDetails=true` to collect only project-level details.
-VB.NET|`sonar.vbnet.vstest.reportsPaths`|Paths to VSTest execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
-VB.NET|`sonar.vbnet.nunit.reportsPaths`|Paths to NUnit execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
-VB.NET|`sonar.vbnet.xunit.reportsPaths`|Paths to xUnit execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
+### All Languages
+  
+Analysis parameter|Description
+----|----
+`sonar.testExecutionReportPaths`|Comma-delimited list of paths to execution reports in the [Generic Execution Data](/analysis/generic-test/) format. The paths must be relative to the project's base directory (root module).
+
+### C/C++/Objective-C
+
+Analysis parameter|Description
+----|----
+`sonar.cfamily.cppunit.reportsPath`|Path to the directory holding the [CPPUnit](http://sourceforge.net/projects/cppunit/) reports. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
+
+### C&#x23;
+
+Analysis parameter|Description
+----|----
+`sonar.cs.vstest.reportsPaths`|Paths to VSTest reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
+`sonar.cs.nunit.reportsPaths`|Paths to NUnit execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
+`sonar.cs.xunit.reportsPaths`|Paths to xUnit execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
+
+### Go
+
+Analysis parameter|Description
+----|----
+`sonar.go.tests.reportPaths`|Comma-delimited list of paths to unit test report files. Paths may be absolute or relative to project root.
+
+### Java, Kotlin
+
+Analysis parameter|Description
+----|----
+`sonar.junit.reportPaths`|Comma-delimited list of paths to Surefire XML-format reports.
+
+### Javascript and Typescript
+
+Analysis parameter|Description
+----|----
+&nbsp;|You can use [jest-sonar-reporter](https://www.npmjs.com/package/jest-sonar-reporter) or [karma-sonarqube-unit-reporter](https://github.com/tornaia/karma-sonarqube-unit-reporter) to create reports in the [Generic Execution Data](/analysis/generic-test/) format. Both packages are available on npm.
+
+### PHP
+
+Analysis parameter|Description
+----|----
+`sonar.php.tests.reportPath`|Path to the PHPUnit unit test execution report file. Path may be absolute or relative to project root.
+
+### Python  
+
+Analysis parameter|Description
+----|----
+`sonar.python.xunit.reportPath`|Path to unit test execution report. Leave unset to use the default (`xunit-reports/xunit-result-*.xml`). Path wildcards (see above) are supported. If any paths in the report are invalid, set `sonar.python.xunit.skipDetails=true` to collect only project-level details.
+
+### VB.NET
+
+Analysis parameter|Description
+----|----
+`sonar.vbnet.vstest.reportsPaths`|Paths to VSTest execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
+`sonar.vbnet.nunit.reportsPaths`|Paths to NUnit execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
+`sonar.vbnet.xunit.reportsPaths`|Paths to xUnit execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available.
 
 ## Importing .NET reports
 To import .NET reports, the report generation process must be executed after the begin step and before the end MSBuild command. The following steps detail importing .NET reports:
@@ -76,3 +211,26 @@ To import .NET reports, the report generation process must be executed after the
 1. Run the SonarScanner.MSBuild.exe `end` command
 
 For more information, see the [Generate Reports for C#, VB.net Community Post](https://community.sonarsource.com/t/coverage-test-data-generate-reports-for-c-vb-net/9871).
+
+## Troubleshooting 
+
+### Why doesn't coverage in SonarQube match my coverage tool?
+Code coverage metrics may look different between SonarQube and the tool you've used to gather them. Often, this is because the two aren't using the same metrics.  
+
+External tools often use line coverage, calculated by dividing covered lines (lines to cover - uncovered lines) by the total number of executable lines (lines to cover). 
+
+SonarQube uses the covered lines from the imported coverage report and the executable lines (or lines to cover) to calculate its coverage metrics. SonarQube computes coverage as follows:
+
+```
+Coverage = (CT + CF + LC)/(2*B + EL)
+where
+CT = conditions that have been evaluated to ‘true’ at least once
+CF = conditions that have been evaluated to ‘false’ at least once
+LC = covered lines = lines_to_cover - uncovered_lines
+B = total number of conditions
+EL = total number of executable lines (lines_to_cover)
+```
+
+SonarQube might also compute line coverage differently from your external tool. This is because the lines to cover may not be the same according to SonarQube and to the tool.
+
+For more information on what SonarQube considers a line of code, see the **Tests** section on the [metric-definitions page](/user-guide/metric-definitions/). 
\ No newline at end of file
diff --git a/server/sonar-docs/static/SonarQubeNavigationTree.json b/server/sonar-docs/static/SonarQubeNavigationTree.json
index d3aa87957fc..8544d7eb058 100644
--- a/server/sonar-docs/static/SonarQubeNavigationTree.json
+++ b/server/sonar-docs/static/SonarQubeNavigationTree.json
@@ -54,6 +54,7 @@
         ]
       },
       "/analysis/coverage/",
+      "/analysis/generic-test/",
       {
         "title": "Importing External Issues",
         "children": [
@@ -62,7 +63,6 @@
 		]
       },
       "/analysis/background-tasks/",
-      "/analysis/generic-test/",
 	  "/analysis/pull-request/",
       {
         "title": "Branches",
diff --git a/server/sonar-docs/static/StaticNavigationTree.json b/server/sonar-docs/static/StaticNavigationTree.json
index 12ce1e53010..11cc337479b 100644
--- a/server/sonar-docs/static/StaticNavigationTree.json
+++ b/server/sonar-docs/static/StaticNavigationTree.json
@@ -88,6 +88,7 @@
         ]
       },
       "/analysis/coverage/",
+      "/analysis/generic-test/",
       {
         "title": "Importing External Issues",
         "children": [
@@ -96,7 +97,6 @@
 		]
       },
       "/analysis/background-tasks/",
-      "/analysis/generic-test/",
 	  "/analysis/pull-request/",
       {
         "title": "Branches",