Improve documentation

Author: nyamsprod

docs/1.0/building-blocks.md

@@ -16,7 +16,7 @@ It is the **base construct** used to measure resource consumption across differe
 
 `Snapshots` are **read-only** after creation.
 
-### Create a Snapshot
+### Take a Snapshot
 
 You can create a snapshot using the `now()` static method:
 
@@ -45,8 +45,6 @@ $snapshot->cpuSystemTime;
 $snapshot->hrtime;
 ```
 
-### Labels
-
 You can optionally attach a label to a `Snapshot`. If you do not assign a label to the snapshot, one will be 
 automatically assigned to it. Labels can include lowercase letters, digits, dots, underscores,
 and hyphens—but cannot start or end with a symbol, nor have consecutive symbols.
@@ -96,14 +94,13 @@ $span->range;  // represents the file range between the start and end (the locat
 $span->metrics // the calculated metrics computed from the 2 snapshots.
 ```
 
-### Label
 
 The `label` property is similar to the snapshot identity and uses the same requirements. But, in contrast to
 the `Snapshot`, **the label value is mandatory**.
 
-### Metrics
+## Metrics
 
-The `metrics` property is a `Metrics` value object which exposes the following readonly metric:
+The `Span::metrics` property is a `Metrics` value object which exposes the following readonly metric:
 
 - `executionTime`
 - `cpuTime`
@@ -129,9 +126,9 @@ $span->metrics->realPeakMemoryUsage;       // in bytes
 $span->metrics->realPeakMemoryUsageGrowth; // in bytes
 ```
 
-### Call Location Range
+## Call Location Range
 
-The `range` property is a `CallRange` value object which allows comparing the call location between
+The `Spab::range` property is a `CallRange` value object which allows comparing the call location between
 the starting and the ending snapshots.
 
 ```php
@@ -166,7 +163,7 @@ $span->range->isDifferentLine(); //returns false if the both locations are the s
 The `Report` value object represents a **profiling or metrics summary** of a process, function or operation. It encapsulates **row-level statistics**
 for each metric type (CPU time, memory usage, etc.) and provides **column-oriented access** to aggregated metrics.
 
-### Accessing Row-Level Statistics
+### Row-Level Statistics
 
 You can retrieve a single row of metrics ( a `Statistics` object) by metric type:
 
@@ -177,7 +174,7 @@ $report = stack_report(fn () => true, iterations: 50);
 $cpuRow = $report->row(MetricType::CpuTime); //returns a Statistics object
 ```
 
-### Accessing Column-Level Aggregated Metrics
+### Column-Level Metrics
 
 You can also retrieve aggregated metrics (like min, max, average) **across all types** for a given aggregation:
 
@@ -230,7 +227,7 @@ All the value objects can be
 - JSON-encoded via `json_encode` (implementing the `JsonSerializable` interface)
 - Returned in a **human-readable** format via `toHuman()`. (except for the `CallLocation` and the `CallRange` objects.
 
-### Full human-readable export
+### Human-readable export
 
 The human-readable export automatically converts **nanoseconds** and **bytes** into more human-friendly
 formats depending on the recorded values.

docs/1.0/command.md

@@ -211,9 +211,9 @@ php vendor/bin/stackwatch --path=PATH [options]
 ```
 Apart from the `path` argument, all the other command line options **are optional**.
 
-### Command Line Options
+## Command Line Options
 
-#### Configuration
+### Configuration
 
 **`-p, --path=PATH`**  
 Path to scan for PHP files to profile. **Required.** The path can be a file or a directory.
@@ -228,7 +228,7 @@ Display the help message.
 **`-V, --version`**  
 Display the version and exit.
 
-#### Output
+### Output
 
 **`-f, --format=FORMAT`**  
 Output format. Can be either `'text'` or `'json'`. Default is `'text'`. Use `'text'` for human-readable
@@ -246,7 +246,7 @@ Pretty-print the JSON/NDJSON output. **JSON only.**
 **`--no-progress`**  
 Hides the progress bar
 
-#### Selection
+### Selection
 
 **`-d, --depth=DEPTH`**  
 Recursion depth. `0` means scan only the current directory. By default, recursion is unlimited.
@@ -266,7 +266,7 @@ Only run the profiles for methods with the listed visibilities. The visibility i
 And can only take `private`, `protected` or `public` values. By default, all methods are run
 regardless of their visibility status.
 
-#### Execution
+### Execution
 
 **`-x, --isolation`**  
 Profile each file in isolation.

docs/1.0/timeline.md

@@ -209,7 +209,7 @@ The `Timeline` class provides a `filter()` method to extract a subset of its `Sn
 - The callback must return `true` for a Snapshot to be included in the results.
 - The method returns a list of matching Snapshots.
 
-### Example
+Here's a simple filtering example:
 
 ```php
 use Bakame\Stackwatch\MemoryUnit;