diff --git a/docs/content/instrumenting/_index.md b/docs/content/instrumenting/_index.md
index 13bbc6b6..6b330a58 100644
--- a/docs/content/instrumenting/_index.md
+++ b/docs/content/instrumenting/_index.md
@@ -3,10 +3,20 @@ title: Instrumenting
 weight: 2
 ---
 
-Four types of metric are offered: Counter, Gauge, Summary and Histogram.
-See the documentation on [metric types](http://prometheus.io/docs/concepts/metric_types/)
+Six metric types are available. Pick based on what your value does:
+
+| Type | Value goes | Use for |
+|------|-----------|---------|
+| [Counter](counter/) | only up | requests served, errors, bytes sent |
+| [Gauge](gauge/) | up and down | queue depth, active connections, memory usage |
+| [Histogram](histogram/) | observations in buckets | request latency, request size — when you need quantiles in queries |
+| [Summary](summary/) | observations (count + sum) | request latency, request size — when average is enough |
+| [Info](info/) | static key-value pairs | build version, environment metadata |
+| [Enum](enum/) | one of N states | task state, lifecycle phase |
+
+See the Prometheus documentation on [metric types](https://prometheus.io/docs/concepts/metric_types/)
 and [instrumentation best practices](https://prometheus.io/docs/practices/instrumentation/#counter-vs-gauge-summary-vs-histogram)
-on how to use them.
+for deeper guidance on choosing between Histogram and Summary.
 
 ## Disabling `_created` metrics
 
diff --git a/docs/content/instrumenting/counter.md b/docs/content/instrumenting/counter.md
index 94618025..06f07f53 100644
--- a/docs/content/instrumenting/counter.md
+++ b/docs/content/instrumenting/counter.md
@@ -3,12 +3,14 @@ title: Counter
 weight: 1
 ---
 
-Counters go up, and reset when the process restarts.
+A Counter tracks a value that only ever goes up. Use it for things you count — requests
+served, errors raised, bytes sent. When the process restarts, the counter resets to zero.
 
+If your value can go down, use a [Gauge](../gauge/) instead.
 
 ```python
 from prometheus_client import Counter
-c = Counter('my_failures', 'Description of counter')
+c = Counter('my_failures_total', 'Description of counter')
 c.inc()     # Increment by 1
 c.inc(1.6)  # Increment by given value
 ```
@@ -18,17 +20,110 @@ exposing the time series for counter, a `_total` suffix will be added. This is
 for compatibility between OpenMetrics and the Prometheus text format, as OpenMetrics
 requires the `_total` suffix.
 
-There are utilities to count exceptions raised:
+## Constructor
+
+```python
+Counter(name, documentation, labelnames=(), namespace='', subsystem='', unit='', registry=REGISTRY)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | required | Metric name. A `_total` suffix is appended automatically when exposing the time series. |
+| `documentation` | `str` | required | Help text shown in the `/metrics` output and Prometheus UI. |
+| `labelnames` | `Iterable[str]` | `()` | Names of labels for this metric. See [Labels](../labels/). |
+| `namespace` | `str` | `''` | Optional prefix. |
+| `subsystem` | `str` | `''` | Optional middle component. |
+| `unit` | `str` | `''` | Optional unit suffix appended to the metric name. |
+| `registry` | `CollectorRegistry` | `REGISTRY` | Registry to register with. Pass `None` to skip registration, which is useful in tests where you create metrics without wanting them in the global registry. |
+
+`namespace`, `subsystem`, and `name` are joined with underscores to form the full metric name:
+
+```python
+# namespace='myapp', subsystem='http', name='requests_total'
+# produces: myapp_http_requests_total
+Counter('requests_total', 'Total requests', namespace='myapp', subsystem='http')
+```
+
+## Methods
+
+### `inc(amount=1, exemplar=None)`
+
+Increment the counter by the given amount. The amount must be non-negative.
+
+```python
+c.inc()       # increment by 1
+c.inc(5)      # increment by 5
+c.inc(0.7)    # fractional increments are allowed
+```
+
+To attach trace context to an observation, pass an `exemplar` dict. Exemplars are
+only rendered in OpenMetrics format. See [Exemplars](../exemplars/) for details.
+
+```python
+c.inc(exemplar={'trace_id': 'abc123'})
+```
+
+### `reset()`
+
+Reset the counter to zero. Use this when a logical process restarts without
+restarting the actual Python process.
+
+```python
+c.reset()
+```
+
+### `count_exceptions(exception=Exception)`
+
+Count exceptions raised in a block of code or function. Can be used as a
+decorator or context manager. Increments the counter each time an exception
+of the given type is raised.
 
 ```python
 @c.count_exceptions()
 def f():
-  pass
+    pass
 
 with c.count_exceptions():
-  pass
+    pass
 
-# Count only one type of exception
+# Count only a specific exception type
 with c.count_exceptions(ValueError):
-  pass
-```
\ No newline at end of file
+    pass
+```
+
+## Labels
+
+See [Labels](../labels/) for how to use `.labels()`, `.remove()`, `.remove_by_labels()`, and `.clear()`.
+
+## Real-world example
+
+Tracking HTTP requests by method and status code in a web application:
+
+```python
+from prometheus_client import Counter, start_http_server
+
+REQUESTS = Counter(
+    'requests_total',
+    'Total HTTP requests received',
+    labelnames=['method', 'status'],
+    namespace='myapp',
+)
+EXCEPTIONS = Counter(
+    'exceptions_total',
+    'Total unhandled exceptions',
+    labelnames=['handler'],
+    namespace='myapp',
+)
+
+def handle_request(method, handler):
+    with EXCEPTIONS.labels(handler=handler).count_exceptions():
+        # ... process the request ...
+        status = '200'
+    REQUESTS.labels(method=method, status=status).inc()
+
+if __name__ == '__main__':
+    start_http_server(8000)  # exposes metrics at http://localhost:8000/metrics
+    # ... start your application ...
+```
+
+This produces time series like `myapp_requests_total{method="GET",status="200"}`.
diff --git a/docs/content/instrumenting/enum.md b/docs/content/instrumenting/enum.md
index 102091a1..b1e6169a 100644
--- a/docs/content/instrumenting/enum.md
+++ b/docs/content/instrumenting/enum.md
@@ -3,11 +3,95 @@ title: Enum
 weight: 6
 ---
 
-Enum tracks which of a set of states something is currently in.
+Enum tracks which of a fixed set of states something is currently in. Only one state is active at a time. Use it for things like task state machines or lifecycle phases.
 
 ```python
 from prometheus_client import Enum
 e = Enum('my_task_state', 'Description of enum',
         states=['starting', 'running', 'stopped'])
 e.state('running')
-```
\ No newline at end of file
+```
+
+Enum exposes one time series per state:
+- `<name>{<name>="<state>"}` — 1 if this is the current state, 0 otherwise
+
+The first listed state is the default.
+
+Note: Enum metrics do not work in multiprocess mode.
+
+## Constructor
+
+```python
+Enum(name, documentation, labelnames=(), namespace='', subsystem='', unit='', registry=REGISTRY, states=[])
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | required | Metric name. |
+| `documentation` | `str` | required | Help text shown in the `/metrics` output and Prometheus UI. |
+| `labelnames` | `Iterable[str]` | `()` | Names of labels for this metric. See [Labels](../labels/). The metric name itself cannot be used as a label name. |
+| `namespace` | `str` | `''` | Optional prefix. |
+| `subsystem` | `str` | `''` | Optional middle component. |
+| `unit` | `str` | `''` | Not supported — raises `ValueError`. Enum metrics cannot have a unit. |
+| `registry` | `CollectorRegistry` | `REGISTRY` | Registry to register with. Pass `None` to skip registration, which is useful in tests where you create metrics without wanting them in the global registry. |
+| `states` | `List[str]` | required | The complete list of valid states. Must be non-empty. The first entry is the initial state. |
+
+`namespace`, `subsystem`, and `name` are joined with underscores to form the full metric name:
+
+```python
+# namespace='myapp', subsystem='worker', name='state'
+# produces: myapp_worker_state
+Enum('state', 'Worker state', states=['idle', 'running', 'error'], namespace='myapp', subsystem='worker')
+```
+
+## Methods
+
+### `state(state)`
+
+Set the current state. The value must be one of the strings passed in the `states` list. Raises `ValueError` if the state is not recognized.
+
+```python
+e.state('running')
+e.state('stopped')
+```
+
+## Labels
+
+See [Labels](../labels/) for how to use `.labels()`, `.remove()`, `.remove_by_labels()`, and `.clear()`.
+
+## Real-world example
+
+Tracking the lifecycle state of a background worker:
+
+```python
+from prometheus_client import Enum, start_http_server
+
+WORKER_STATE = Enum(
+    'worker_state',
+    'Current state of the background worker',
+    states=['idle', 'running', 'error'],
+    namespace='myapp',
+)
+
+def process_job():
+    WORKER_STATE.state('running')
+    try:
+        # ... do work ...
+        pass
+    except Exception:
+        WORKER_STATE.state('error')
+        raise
+    finally:
+        WORKER_STATE.state('idle')
+
+if __name__ == '__main__':
+    start_http_server(8000)  # exposes metrics at http://localhost:8000/metrics
+    # ... start your application ...
+```
+
+This produces:
+```
+myapp_worker_state{myapp_worker_state="idle"} 0.0
+myapp_worker_state{myapp_worker_state="running"} 1.0
+myapp_worker_state{myapp_worker_state="error"} 0.0
+```
diff --git a/docs/content/instrumenting/gauge.md b/docs/content/instrumenting/gauge.md
index 0b1529e9..43168a68 100644
--- a/docs/content/instrumenting/gauge.md
+++ b/docs/content/instrumenting/gauge.md
@@ -3,7 +3,8 @@ title: Gauge
 weight: 2
 ---
 
-Gauges can go up and down.
+A Gauge tracks a value that can go up and down. Use it for things you sample at a
+point in time — active connections, queue depth, memory usage, temperature.
 
 ```python
 from prometheus_client import Gauge
@@ -13,24 +14,145 @@ g.dec(10)    # Decrement by given value
 g.set(4.2)   # Set to a given value
 ```
 
-There are utilities for common use cases:
+## Constructor
 
 ```python
-g.set_to_current_time()   # Set to current unixtime
+Gauge(name, documentation, labelnames=(), namespace='', subsystem='', unit='', registry=REGISTRY, multiprocess_mode='all')
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | required | Metric name. |
+| `documentation` | `str` | required | Help text shown in the `/metrics` output and Prometheus UI. |
+| `labelnames` | `Iterable[str]` | `()` | Names of labels for this metric. See [Labels](../labels/). |
+| `namespace` | `str` | `''` | Optional prefix. |
+| `subsystem` | `str` | `''` | Optional middle component. |
+| `unit` | `str` | `''` | Optional unit suffix appended to the metric name. |
+| `registry` | `CollectorRegistry` | `REGISTRY` | Registry to register with. Pass `None` to skip registration, which is useful in tests where you create metrics without wanting them in the global registry. |
+| `multiprocess_mode` | `str` | `'all'` | How to aggregate this gauge across multiple processes. See [Multiprocess mode](../../multiprocess/). Options: `all`, `liveall`, `min`, `livemin`, `max`, `livemax`, `sum`, `livesum`, `mostrecent`, `livemostrecent`. |
+
+`namespace`, `subsystem`, and `name` are joined with underscores to form the full metric name:
+
+```python
+# namespace='myapp', subsystem='db', name='connections_active'
+# produces: myapp_db_connections_active
+Gauge('connections_active', 'Active DB connections', namespace='myapp', subsystem='db')
+```
+
+## Methods
+
+### `inc(amount=1)`
+
+Increment the gauge by the given amount.
+
+```python
+g.inc()    # increment by 1
+g.inc(3)   # increment by 3
+```
+
+Note: raises `RuntimeError` if `multiprocess_mode` is `mostrecent` or `livemostrecent`.
+
+### `dec(amount=1)`
+
+Decrement the gauge by the given amount.
+
+```python
+g.dec()    # decrement by 1
+g.dec(3)   # decrement by 3
+```
+
+Note: raises `RuntimeError` if `multiprocess_mode` is `mostrecent` or `livemostrecent`.
+
+### `set(value)`
+
+Set the gauge to the given value.
+
+```python
+g.set(42.5)
+```
+
+### `set_to_current_time()`
+
+Set the gauge to the current Unix timestamp in seconds. Useful for tracking
+when an event last occurred.
 
-# Increment when entered, decrement when exited.
+```python
+g.set_to_current_time()
+```
+
+### `track_inprogress()`
+
+Increment the gauge when a block of code or function is entered, and decrement
+it when exited. Can be used as a decorator or context manager.
+
+```python
 @g.track_inprogress()
-def f():
-  pass
+def process_job():
+    pass
 
 with g.track_inprogress():
-  pass
+    pass
+```
+
+### `time()`
+
+Set the gauge to the duration in seconds of the most recent execution of a
+block of code or function. Unlike `Histogram.time()` and `Summary.time()`,
+which accumulate all observations, this overwrites the gauge with the latest
+duration each time. Can be used as a decorator or context manager.
+
+```python
+@g.time()
+def process():
+    pass
+
+with g.time():
+    pass
+```
+
+### `set_function(f)`
+
+Bind a callback function that returns the gauge value. The function is called
+each time the metric is scraped. All other methods become no-ops after calling
+this.
+
+```python
+queue = []
+g.set_function(lambda: len(queue))
 ```
 
-A Gauge can also take its value from a callback:
+## Labels
+
+See [Labels](../labels/) for how to use `.labels()`, `.remove()`, `.remove_by_labels()`, and `.clear()`.
+
+## Real-world example
+
+Tracking active database connections and queue depth:
 
 ```python
-d = Gauge('data_objects', 'Number of objects')
-my_dict = {}
-d.set_function(lambda: len(my_dict))
-```
\ No newline at end of file
+from prometheus_client import Gauge, start_http_server
+
+ACTIVE_CONNECTIONS = Gauge(
+    'connections_active',
+    'Number of active database connections',
+    namespace='myapp',
+)
+QUEUE_SIZE = Gauge(
+    'job_queue_size',
+    'Number of jobs waiting in the queue',
+    namespace='myapp',
+)
+
+job_queue = []
+QUEUE_SIZE.set_function(lambda: len(job_queue))
+
+def acquire_connection():
+    ACTIVE_CONNECTIONS.inc()
+
+def release_connection():
+    ACTIVE_CONNECTIONS.dec()
+
+if __name__ == '__main__':
+    start_http_server(8000)  # exposes metrics at http://localhost:8000/metrics
+    # ... start your application ...
+```
diff --git a/docs/content/instrumenting/histogram.md b/docs/content/instrumenting/histogram.md
index cb85f183..8975d859 100644
--- a/docs/content/instrumenting/histogram.md
+++ b/docs/content/instrumenting/histogram.md
@@ -3,8 +3,9 @@ title: Histogram
 weight: 4
 ---
 
-Histograms track the size and number of events in buckets.
-This allows for aggregatable calculation of quantiles.
+A Histogram samples observations and counts them in configurable buckets. Use it
+when you want to track distributions — request latency, response sizes — and need
+to calculate quantiles (p50, p95, p99) in your queries.
 
 ```python
 from prometheus_client import Histogram
@@ -12,16 +13,113 @@ h = Histogram('request_latency_seconds', 'Description of histogram')
 h.observe(4.7)    # Observe 4.7 (seconds in this case)
 ```
 
-The default buckets are intended to cover a typical web/rpc request from milliseconds to seconds.
-They can be overridden by passing `buckets` keyword argument to `Histogram`.
+A Histogram exposes three time series per metric:
+- `<name>_bucket{le="<bound>"}` — count of observations with value ≤ le (cumulative)
+- `<name>_sum` — sum of all observed values
+- `<name>_count` — total number of observations
 
-There are utilities for timing code:
+## Constructor
+
+```python
+Histogram(name, documentation, labelnames=(), namespace='', subsystem='', unit='', registry=REGISTRY, buckets=DEFAULT_BUCKETS)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | required | Metric name. |
+| `documentation` | `str` | required | Help text shown in the `/metrics` output and Prometheus UI. |
+| `labelnames` | `Iterable[str]` | `()` | Names of labels for this metric. See [Labels](../labels/). Note: `le` is reserved and cannot be used as a label name. |
+| `namespace` | `str` | `''` | Optional prefix. |
+| `subsystem` | `str` | `''` | Optional middle component. |
+| `unit` | `str` | `''` | Optional unit suffix appended to the metric name. |
+| `registry` | `CollectorRegistry` | `REGISTRY` | Registry to register with. Pass `None` to skip registration, which is useful in tests where you create metrics without wanting them in the global registry. |
+| `buckets` | `Sequence[float]` | `DEFAULT_BUCKETS` | Upper bounds of the histogram buckets. Must be in ascending order. `+Inf` is always appended automatically. |
+
+`namespace`, `subsystem`, and `name` are joined with underscores to form the full metric name:
+
+```python
+# namespace='myapp', subsystem='http', name='request_duration_seconds'
+# produces: myapp_http_request_duration_seconds
+Histogram('request_duration_seconds', 'Latency', namespace='myapp', subsystem='http')
+```
+
+Default buckets are intended to cover typical web/RPC request latency in seconds and are
+accessible as `Histogram.DEFAULT_BUCKETS`:
+
+```
+.005, .01, .025, .05, .075, .1, .25, .5, .75, 1.0, 2.5, 5.0, 7.5, 10.0, +Inf
+```
+
+To override with buckets tuned to your workload:
+
+```python
+h = Histogram('request_latency_seconds', 'Latency', buckets=[.1, .5, 1, 2, 5])
+```
+
+## Methods
+
+### `observe(amount, exemplar=None)`
+
+Record a single observation. The amount is typically positive or zero.
+
+```python
+h.observe(0.43)   # observe 430ms
+```
+
+To attach trace context to an observation, pass an `exemplar` dict. Exemplars are
+only rendered in OpenMetrics format. See [Exemplars](../exemplars/) for details.
+
+```python
+h.observe(0.43, exemplar={'trace_id': 'abc123'})
+```
+
+### `time()`
+
+Observe the duration in seconds of a block of code or function and add it to the
+histogram. Every call accumulates — unlike `Gauge.time()`, which only keeps the
+most recent duration. Can be used as a decorator or context manager.
 
 ```python
 @h.time()
-def f():
-  pass
+def process():
+    pass
 
 with h.time():
-  pass
-```
\ No newline at end of file
+    pass
+```
+
+## Labels
+
+See [Labels](../labels/) for how to use `.labels()`, `.remove()`, `.remove_by_labels()`, and `.clear()`.
+
+## Real-world example
+
+Tracking HTTP request latency with custom buckets tuned to the workload:
+
+```python
+from prometheus_client import Histogram, start_http_server
+
+REQUEST_LATENCY = Histogram(
+    'request_duration_seconds',
+    'HTTP request latency',
+    labelnames=['method', 'endpoint'],
+    namespace='myapp',
+    buckets=[.01, .05, .1, .25, .5, 1, 2.5, 5],
+)
+
+def handle_request(method, endpoint):
+    with REQUEST_LATENCY.labels(method=method, endpoint=endpoint).time():
+        # ... handle the request ...
+        pass
+
+if __name__ == '__main__':
+    start_http_server(8000)  # exposes metrics at http://localhost:8000/metrics
+    # ... start your application ...
+```
+
+This produces time series like:
+```
+myapp_request_duration_seconds_bucket{method="GET",endpoint="/api/users",le="0.1"} 42
+myapp_request_duration_seconds_sum{method="GET",endpoint="/api/users"} 3.7
+myapp_request_duration_seconds_count{method="GET",endpoint="/api/users"} 50
+```
diff --git a/docs/content/instrumenting/info.md b/docs/content/instrumenting/info.md
index 6334d92b..6e369de7 100644
--- a/docs/content/instrumenting/info.md
+++ b/docs/content/instrumenting/info.md
@@ -3,10 +3,83 @@ title: Info
 weight: 5
 ---
 
-Info tracks key-value information, usually about a whole target.
+Info tracks key-value pairs that describe a target — build version, configuration, or environment metadata. The values are static: once set, the metric outputs a single time series with all key-value pairs as labels and a constant value of 1.
 
 ```python
 from prometheus_client import Info
 i = Info('my_build_version', 'Description of info')
 i.info({'version': '1.2.3', 'buildhost': 'foo@bar'})
 ```
+
+Info exposes one time series per metric:
+- `<name>_info{<key>="<value>", ...}` — always 1; the key-value pairs become labels
+
+Note: Info metrics do not work in multiprocess mode.
+
+## Constructor
+
+```python
+Info(name, documentation, labelnames=(), namespace='', subsystem='', unit='', registry=REGISTRY)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | required | Metric name. A `_info` suffix is appended automatically when exposing the time series. |
+| `documentation` | `str` | required | Help text shown in the `/metrics` output and Prometheus UI. |
+| `labelnames` | `Iterable[str]` | `()` | Names of labels for this metric. See [Labels](../labels/). Keys passed to `.info()` must not overlap with these label names. |
+| `namespace` | `str` | `''` | Optional prefix. |
+| `subsystem` | `str` | `''` | Optional middle component. |
+| `unit` | `str` | `''` | Not supported — raises `ValueError`. Info metrics cannot have a unit. |
+| `registry` | `CollectorRegistry` | `REGISTRY` | Registry to register with. Pass `None` to skip registration, which is useful in tests where you create metrics without wanting them in the global registry. |
+
+`namespace`, `subsystem`, and `name` are joined with underscores to form the full metric name:
+
+```python
+# namespace='myapp', subsystem='http', name='build'
+# produces: myapp_http_build_info
+Info('build', 'Build information', namespace='myapp', subsystem='http')
+```
+
+## Methods
+
+### `info(val)`
+
+Set the key-value pairs for this metric. `val` must be a `dict[str, str]` — both keys and values must be strings. Keys must not overlap with the metric's label names and values cannot be `None`. Calling `info()` again overwrites the previous value.
+
+```python
+i.info({'version': '1.4.2', 'revision': 'abc123', 'branch': 'main'})
+```
+
+## Labels
+
+See [Labels](../labels/) for how to use `.labels()`, `.remove()`, `.remove_by_labels()`, and `.clear()`.
+
+## Real-world example
+
+Exposing application build metadata so dashboards can join on version:
+
+```python
+from prometheus_client import Info, start_http_server
+
+BUILD_INFO = Info(
+    'build',
+    'Application build information',
+    namespace='myapp',
+)
+
+BUILD_INFO.info({
+    'version': '1.4.2',
+    'revision': 'abc123def456',
+    'branch': 'main',
+    'build_date': '2024-01-15',
+})
+
+if __name__ == '__main__':
+    start_http_server(8000)  # exposes metrics at http://localhost:8000/metrics
+    # ... start your application ...
+```
+
+This produces:
+```
+myapp_build_info{branch="main",build_date="2024-01-15",revision="abc123def456",version="1.4.2"} 1.0
+```
diff --git a/docs/content/instrumenting/labels.md b/docs/content/instrumenting/labels.md
index ebf80b56..39ad29c8 100644
--- a/docs/content/instrumenting/labels.md
+++ b/docs/content/instrumenting/labels.md
@@ -5,8 +5,8 @@ weight: 7
 
 All metrics can have labels, allowing grouping of related time series.
 
-See the best practices on [naming](http://prometheus.io/docs/practices/naming/)
-and [labels](http://prometheus.io/docs/practices/instrumentation/#use-labels).
+See the best practices on [naming](https://prometheus.io/docs/practices/naming/)
+and [labels](https://prometheus.io/docs/practices/instrumentation/#use-labels).
 
 Taking a counter as an example:
 
@@ -35,4 +35,33 @@ from prometheus_client import Counter
 c = Counter('my_requests_total', 'HTTP Failures', ['method', 'endpoint'])
 c.labels('get', '/')
 c.labels('post', '/submit')
+```
+
+## Removing labelsets
+
+### `remove(*labelvalues)`
+
+Remove a specific labelset from the metric. Values must be passed in the same
+order as `labelnames` were declared.
+
+```python
+c = Counter('my_requests_total', 'HTTP Failures', ['method', 'endpoint'])
+c.labels('get', '/').inc()
+c.remove('get', '/')
+```
+
+### `remove_by_labels(labels)`
+
+Remove all labelsets that partially match the given dict of label names and values.
+
+```python
+c.remove_by_labels({'method': 'get'})  # removes all labelsets where method='get'
+```
+
+### `clear()`
+
+Remove all labelsets from the metric at once.
+
+```python
+c.clear()
 ```
\ No newline at end of file
diff --git a/docs/content/instrumenting/summary.md b/docs/content/instrumenting/summary.md
index fa407496..55428ecb 100644
--- a/docs/content/instrumenting/summary.md
+++ b/docs/content/instrumenting/summary.md
@@ -3,7 +3,12 @@ title: Summary
 weight: 3
 ---
 
-Summaries track the size and number of events.
+A Summary samples observations and tracks the total count and sum. Use it when
+you want to track the size or duration of events and compute averages, but do not
+need per-bucket breakdown or quantiles in your Prometheus queries.
+
+The Python client does not compute quantiles locally. If you need p50/p95/p99,
+use a [Histogram](../histogram/) instead.
 
 ```python
 from prometheus_client import Summary
@@ -11,15 +16,95 @@ s = Summary('request_latency_seconds', 'Description of summary')
 s.observe(4.7)    # Observe 4.7 (seconds in this case)
 ```
 
-There are utilities for timing code:
+A Summary exposes two time series per metric:
+- `<name>_count` — total number of observations
+- `<name>_sum` — sum of all observed values
+
+## Constructor
+
+```python
+Summary(name, documentation, labelnames=(), namespace='', subsystem='', unit='', registry=REGISTRY)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | required | Metric name. |
+| `documentation` | `str` | required | Help text shown in the `/metrics` output and Prometheus UI. |
+| `labelnames` | `Iterable[str]` | `()` | Names of labels for this metric. See [Labels](../labels/). Note: `quantile` is reserved and cannot be used as a label name. |
+| `namespace` | `str` | `''` | Optional prefix. |
+| `subsystem` | `str` | `''` | Optional middle component. |
+| `unit` | `str` | `''` | Optional unit suffix appended to the metric name. |
+| `registry` | `CollectorRegistry` | `REGISTRY` | Registry to register with. Pass `None` to skip registration, which is useful in tests where you create metrics without wanting them in the global registry. |
+
+`namespace`, `subsystem`, and `name` are joined with underscores to form the full metric name:
+
+```python
+# namespace='myapp', subsystem='worker', name='task_duration_seconds'
+# produces: myapp_worker_task_duration_seconds
+Summary('task_duration_seconds', 'Task duration', namespace='myapp', subsystem='worker')
+```
+
+## Methods
+
+### `observe(amount)`
+
+Record a single observation. The amount is typically positive or zero.
+
+```python
+s.observe(0.43)   # observe 430ms
+s.observe(1024)   # observe 1024 bytes
+```
+
+### `time()`
+
+Observe the duration in seconds of a block of code or function and add it to the
+summary. Every call accumulates — unlike `Gauge.time()`, which only keeps the
+most recent duration. Can be used as a decorator or context manager.
 
 ```python
 @s.time()
-def f():
-  pass
+def process():
+    pass
 
 with s.time():
-  pass
+    pass
+```
+
+## Labels
+
+See [Labels](../labels/) for how to use `.labels()`, `.remove()`, `.remove_by_labels()`, and `.clear()`.
+
+## Real-world example
+
+Tracking the duration of background tasks:
+
+```python
+from prometheus_client import Summary, start_http_server
+
+TASK_DURATION = Summary(
+    'task_duration_seconds',
+    'Time spent processing background tasks',
+    labelnames=['task_type'],
+    namespace='myapp',
+)
+
+def run_task(task_type, task):
+    with TASK_DURATION.labels(task_type=task_type).time():
+        # ... run the task ...
+        pass
+
+if __name__ == '__main__':
+    start_http_server(8000)  # exposes metrics at http://localhost:8000/metrics
+    # ... start your application ...
+```
+
+This produces:
+```
+myapp_task_duration_seconds_count{task_type="email"} 120
+myapp_task_duration_seconds_sum{task_type="email"} 48.3
 ```
 
-The Python client doesn't store or expose quantile information at this time.
\ No newline at end of file
+You can compute the average duration in PromQL as:
+```
+rate(myapp_task_duration_seconds_sum[5m]) / rate(myapp_task_duration_seconds_count[5m])
+```