docs: follow-up fixes for collect() generator examples (#1169) (#1172)

* 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>

* docs: split InfoMetricFamily example into two separate blocks

The single block with two yield statements looked like one collect() yielding
both patterns. Split into labelled prose + code pairs to make clear they are
alternatives, not sequential yields.

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

---------

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
@@ -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'})