docs: clarify collect() generator usage and API Reference snippet context

Add a note to the collect() protocol section explaining that yield is idiomatic
(generator iterates lazily, no state between scrapes) and a preamble to the API
Reference section clarifying that code snippets belong inside a collect() method.

Follows up on review feedback in #1169.

Signed-off-by: k1chik <kkukdia@gmail.com>

Author: k1chik

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