1 files changed, 33 insertions, 21 deletions

diff --git a/docs/test/coverage.md b/docs/test/coverage.md
index 229da41f2..503b5abf6 100644
--- a/docs/test/coverage.md
+++ b/docs/test/coverage.md
@@ -1,12 +1,11 @@
-`bun:test` supports seeing which lines of code are covered by tests. To use this feature, pass `--coverage` to the CLI:
+Bun's test runner now supports built-in _code coverage reporting_. This makes it easy to see how much of the codebase is covered by tests, and find areas that are not currently well-tested.
 
-```sh
-bun test --coverage
-```
+## Enabling coverage
 
-It will print out a coverage report to the console:
+`bun:test` supports seeing which lines of code are covered by tests. To use this feature, pass `--coverage` to the CLI. It will print out a coverage report to the console:
 
 ```js
+$ bun test --coverage
 -------------|---------|---------|-------------------
 File         | % Funcs | % Lines | Uncovered Line #s
 -------------|---------|---------|-------------------
@@ -26,32 +25,45 @@ All files    |   38.89 |   42.11 |
 -------------|---------|---------|-------------------
 ```
 
-If coverage is below a threshold, `bun:test` will exit with a non-zero exit code to indicate the failure.
+To always enable coverage reporting by default, add the following line to your `bunfig.toml`:
 
-### Configuring coverage
+```toml
+[test]
 
-`bunfig.toml` supports configuring coverage:
+# always enable coverage
+coverage = true
+```
+
+By default coverage reports will _include_ test files and _exclude_ sourcemaps. This is usually what you want, but it can be configured otherwise in `bunfig.toml`.
 
 ```toml
 [test]
+coverageSkipTestFiles = true       # default false
+```
 
-# Always enable coverage
-coverage = true
+### Coverage thresholds
 
-# Anything less than 90% coverage will fail the test
-# coverageThreshold = 0.9
-coverageThreshold = { line = 0.9, function = 0.9 }
+{% callout %}
+**Note** — Support for coverage reporting was added in Bun v0.7.3.
+{% /callout %}
 
+It is possible to specify a coverage threshold in `bunfig.toml`. If your test suite does not meet or exceed this threshold, `bun test` will exit with a non-zero exit code to indicate the failure.
 
-# Don't include .test.* files in coverage reports
-coverageSkipTestFiles = true
+```toml
+[test]
 
-# Disable sourcemap support in coverage reports
-# By default, coverage reports will automatically use Bun's internal sourcemap.
-# You probably don't want to configure this
-# coverageIgnoreSourcemaps = false
+# to require 90% line-level and function-level coverage
+coverageThreshold = 0.9
+
+# to set different thresholds for lines and functions
+coverageThreshold = { line = 0.9, function = 0.9 }
 ```
 
-`coverageThreshold` can be either a number or an object with `line` and `function` keys. When a number, it is treated as both the line and function threshold.
+### Sourcemaps
 
-Coverage support was added in Bun v0.7.3.
+Internally, Bun transpiles all files by default, so Bun automatically generates an internal [source map](https://web.dev/source-maps/) that maps lines of your original source code onto Bun's internal representation. If for any reason you want to disable this, set `test.coverageIgnoreSourcemaps` to `false`; this will rarely be desirable outside of advanced use cases.
+
+```toml
+[test]
+coverageIgnoreSourcemaps = true   # default false
+```