docs(coverage): overall improvements (#2412)

* chore: ignore formatter on markdown files

* docs(coverage): ignoring code section

* docs(coverage): document each coverage option clearly

.vscode/settings.json

@@ -7,5 +7,8 @@
   "[json]": {
     "editor.formatOnSave": false
   },
+  "[markdown]": {
+    "editor.formatOnSave": false
+  },
   "prettier.enable": false
 }

docs/config/index.md

@@ -506,9 +506,6 @@ Isolate environment for each test file. Does not work if you disable [`--threads
 
 ### coverage
 
-- **Type:** `CoverageC8Options | CoverageIstanbulOptions`
-- **Default:** `undefined`
-
 You can use [`c8`](https://github.com/bcoe/c8) or [`istanbul`](https://istanbul.js.org/) for coverage collection.
 
 #### provider
@@ -518,74 +515,185 @@ You can use [`c8`](https://github.com/bcoe/c8) or [`istanbul`](https://istanbul.
 
 Use `provider` to select the tool for coverage collection.
 
-#### CoverageC8Options
-
-Used when `provider: 'c8'` is set. Coverage options are passed to [`c8`](https://github.com/bcoe/c8).
+#### enabled
 
-#### CoverageIstanbulOptions
+- **Type:** `boolean`
+- **Default:** `false`
+- **Available for providers:** `'c8' | 'istanbul'`
 
-Used when `provider: 'istanbul'` is set.
+Enables coverage collection. Can be overriden using `--coverage` CLI option.
 
-##### include
+#### include
 
 - **Type:** `string[]`
 - **Default:** `['**']`
+- **Available for providers:** `'c8' | 'istanbul'`
 
 List of files included in coverage as glob patterns
 
-##### exclude
+#### extension
+
+- **Type:** `string | string[]`
+- **Default:** `['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.vue', '.svelte']`
+- **Available for providers:** `'c8' | 'istanbul'`
+
+#### exclude
 
 - **Type:** `string[]`
-- **Default:** `['coverage/**', 'dist/**', 'packages/*/test{,s}/**', '**/*.d.ts', 'cypress/**', 'test{,s}/**', 'test{,-*}.{js,cjs,mjs,ts,tsx,jsx}', '**/*{.,-}test.{js,cjs,mjs,ts,tsx,jsx}', '**/*{.,-}spec.{js,cjs,mjs,ts,tsx,jsx}', '**/__tests__/**', '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress}.config.{js,cjs,mjs,ts}', '**/.{eslint,mocha,prettier}rc.{js,cjs,yml}']`
+- **Default:**
+```js
+[
+  'coverage/**',
+  'dist/**',
+  'packages/*/test{,s}/**',
+  '**/*.d.ts',
+  'cypress/**',
+  'test{,s}/**',
+  'test{,-*}.{js,cjs,mjs,ts,tsx,jsx}',
+  '**/*{.,-}test.{js,cjs,mjs,ts,tsx,jsx}',
+  '**/*{.,-}spec.{js,cjs,mjs,ts,tsx,jsx}',
+  '**/__tests__/**',
+  '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress}.config.*',
+  '**/.{eslint,mocha,prettier}rc.{js,cjs,yml}',
+]
+```
+- **Available for providers:** `'c8' | 'istanbul'`
 
 List of files excluded from coverage as glob patterns.
 
-##### skipFull
+#### all
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Available for providers:** `'c8' | 'istanbul'`
+
+Whether to include all files, including the untested ones into report.
+
+#### clean
+
+- **Type:** `boolean`
+- **Default:** `true`
+- **Available for providers:** `'c8' | 'istanbul'`
+
+Clean coverage results before running tests
+
+#### cleanOnRerun
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Available for providers:** `'c8' | 'istanbul'`
+
+Clean coverage report on watch rerun
+
+#### reportsDirectory
+
+- **Type:** `string`
+- **Default:** `'./coverage'`
+- **Available for providers:** `'c8' | 'istanbul'`
+
+Directory to write coverage report to.
+When using `c8` provider a temporary `/tmp` directory is created for [V8 coverage results](https://nodejs.org/api/cli.html#coverage-output).
+
+#### reporter
+
+- **Type:** `string | string[]`
+- **Default:** `['text', 'html', 'clover', 'json']`
+- **Available for providers:** `'c8' | 'istanbul'`
+
+Coverage reporters to use. See [istanbul documentation](https://istanbul.js.org/docs/advanced/alternative-reporters/) for detailed list of all reporters.
+
+
+#### skipFull
 
 - **Type:** `boolean`
 - **Default:** `false`
+- **Available for providers:** `'c8' | 'istanbul'`
 
 Do not show files with 100% statement, branch, and function coverage.
 
-##### perFile
+#### perFile
 
 - **Type:** `boolean`
 - **Default:** `false`
+- **Available for providers:** `'c8' | 'istanbul'`
 
 Check thresholds per file.
+See `lines`, `functions`, `branches` and `statements` for the actual thresholds.
 
-##### lines
+#### lines
 
 - **Type:** `number`
+- **Available for providers:** `'c8' | 'istanbul'`
 
 Threshold for lines.
+See [istanbul documentation](https://github.com/istanbuljs/nyc#coverage-thresholds) for more information.
 
-##### functions
+#### functions
 
 - **Type:** `number`
+- **Available for providers:** `'c8' | 'istanbul'`
 
 Threshold for functions.
+See [istanbul documentation](https://github.com/istanbuljs/nyc#coverage-thresholds) for more information.
 
-##### branches
+#### branches
 
 - **Type:** `number`
+- **Available for providers:** `'c8' | 'istanbul'`
 
 Threshold for branches.
+See [istanbul documentation](https://github.com/istanbuljs/nyc#coverage-thresholds) for more information.
 
-##### statements
+#### statements
 
 - **Type:** `number`
+- **Available for providers:** `'c8' | 'istanbul'`
 
 Threshold for statements.
+See [istanbul documentation](https://github.com/istanbuljs/nyc#coverage-thresholds) for more information.
+
+#### allowExternal
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Available for providers:** `'c8'`
+
+Allow files from outside of your cwd.
+
+#### excludeNodeModules
+
+- **Type:** `boolean`
+- **Default:** `true`
+- **Available for providers:** `'c8'`
+
+Exclude coverage under `/node_modules/`.
 
-##### ignoreClassMethods
+#### src
 
 - **Type:** `string[]`
-- **Default:** []
+- **Default:** `process.cwd()`
+- **Available for providers:** `'c8'`
+
+Specifies the directories that are used when `--all` is enabled.
+
+#### 100
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Available for providers:** `'c8'`
+
+Shortcut for `--check-coverage --lines 100 --functions 100 --branches 100 --statements 100`.
+
+#### ignoreClassMethods
+
+- **Type:** `string[]`
+- **Default:** `[]`
+- **Available for providers:** `'istanbul'`
 
 Set to array of class method names to ignore for coverage.
+See [istanbul documentation](https://github.com/istanbuljs/nyc#high-and-low-watermarks) for more information.
 
-##### watermarks
+#### watermarks
 
 - **Type:**
 <!-- eslint-skip -->
@@ -611,13 +719,6 @@ Set to array of class method names to ignore for coverage.
 
 Watermarks for statements, lines, branches and functions.
 
-##### all
-
-- **Type:** `boolean`
-- **Default:** false
-
-Whether to include all files, including the untested ones into report.
-
 ### testNamePattern
 
 - **Type** `string | RegExp`

docs/guide/coverage.md

@@ -88,3 +88,24 @@ export default defineConfig({
 ```
 
 Please refer to the type definition for more details.
+
+## Ignoring code
+
+Both coverage providers have their own ways how to ignore code from coverage reports.
+
+- `c8`: https://github.com/bcoe/c8#ignoring-uncovered-lines-functions-and-blocks
+- `ìstanbul` https://github.com/istanbuljs/nyc#parsing-hints-ignoring-lines
+
+When using Typescript the source codes are transpiled using `esbuild`, which strips all comments from the source codes ([esbuild#516](https://github.com/evanw/esbuild/issues/516)).
+Comments which are considered as [legal comments](https://esbuild.github.io/api/#legal-comments) are preserved.
+
+For `istanbul` provider you can include a `@preserve` keyword in the ignore hint.
+Beware that these ignore hints may now be included in final production build as well.
+
+```diff
+-/* istanbul ignore if */
++/* istanbul ignore if -- @preserve */
+if (condition) {
+```
+
+Unfortunately this does not work for `c8` at the moment.