diff --git a/docs/content/collector/custom.md b/docs/content/collector/custom.md
index 62c0180a..c1979109 100644
--- a/docs/content/collector/custom.md
+++ b/docs/content/collector/custom.md
@@ -47,6 +47,11 @@ can also implement `describe`.
 Returns an iterable of metric family objects (`GaugeMetricFamily`,
 `CounterMetricFamily`, etc.). Called every time the registry is scraped.
 
+Using `yield` is the idiomatic way to implement `collect()` — it turns the method
+into a generator, which the registry iterates lazily without building an intermediate
+list first. Each scrape calls `collect()` fresh, so no state carries over between
+scrapes.
+
 ### `describe()`
 
 Returns an iterable of metric family objects used only to determine the metric
@@ -76,6 +81,10 @@ g.add_metric(['eu-west-1'], 5)
 
 ## API Reference
 
+The examples below show usage inside a `collect()` method body. Each snippet is
+meant to be placed within a custom collector class as shown in the example at the
+top of this page.
+
 ### GaugeMetricFamily
 
 ```python
@@ -232,11 +241,15 @@ InfoMetricFamily(name, documentation, value=None, labels=None)
 | `value` | `Dict[str, str]` | Key-value label pairs that form the info payload. |
 | `timestamp` | `float` or `Timestamp` | Optional Unix timestamp. |
 
+Single unlabelled info metric:
+
 ```python
-# single unlabelled info metric
 yield InfoMetricFamily('build', 'Build metadata', value={'version': '1.2.3', 'commit': 'abc123'})
+```
+
+Labelled — one info metric per service:
 
-# labelled: one info metric per service
+```python
 i = InfoMetricFamily('service_build', 'Per-service build info', labels=['service'])
 i.add_metric(['auth'], {'version': '2.0.1', 'commit': 'def456'})
 i.add_metric(['api'], {'version': '1.9.0', 'commit': 'ghi789'})