Rename SamplyInterval to SamplyTimer

This commit renames all instances of SamplyInterval
or samply_interval to use the word "timer" instead.

After writing a lot of documentation and examples,
I have decided that I think "timer" feels more ergonomic
to use as an abstraction, even though it emits an interval
type marker.

This feels like too much work to interactive rebase back
into the history of this stack, so I'm appending it on.

Author: nordzilla

samply-markers/README.md

@@ -2,6 +2,38 @@
 
 Emit profiler markers that [samply] records and displays in the [Firefox Profiler](https://profiler.firefox.com/) UI.
 
+## Quick Start Demo
+
+The following Fibonacci Sequence example demonstrates recursive function call tracking.
+
+The [`samply_measure!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_measure.html) macro emits an interval marker
+for each recursive call, allowing the profiler to display the complete call tree with timing information for every `fib(n)` invocation.
+
+* [Example profile](https://share.firefox.dev/47ZPJfr)
+
+```rust
+use samply_markers::prelude::*;
+
+// Recursive Fibonacci Sequence
+fn fib(n: u64) -> u64 {
+    samply_measure!({
+        match n {
+            0 => 0,
+            1 => 1,
+            _ => fib(n - 1) + fib(n - 2),
+        }
+    }, marker: {
+        name: format!("fib({n})"),
+    })
+}
+
+fn main() {
+    let n = 10;
+    let value = fib(n);
+    println!("fib({n}) = {}", value);
+}
+```
+
 ## Project Configuration
 
 <br> **1)** Add [samply-markers](https://crates.io/crates/samply-markers) as a dependency to your project's `Cargo.toml`.
@@ -17,8 +49,8 @@ samply-markers = "{version}"
 > Samply markers are designed to no-op by default, so they must be explicitly enabled in order
 > to see them in profiles.
 >
-> * Using samply-markers has effectively zero cost when not enabled.
-> * Using samply-markers does not pull in any additional dependencies when not enabled.
+> * Using [samply-markers](https://crates.io/crates/samply-markers) has effectively zero cost when not enabled.
+> * Using [samply-markers](https://crates.io/crates/samply-markers) does not pull in any additional dependencies when not enabled.
 
 ```toml
 [features]
@@ -36,22 +68,22 @@ inherits = "release"
 debug = true
 ```
 
-<br> **4)** Import the [`samply_markers::prelude`](https://docs.rs/samply-markers/latest/samply_markers/prelude/) to get started adding markers to your code.
-
-<br> **5)** Build your project for profiling, then record the resulting binary with [samply] to capture the emitted markers.
+<br> **4)** Build your project for profiling, then record the resulting binary with [samply] to process the emitted markers.
 
 ```text
 cargo build --profile profiling --features samply-markers
 samply record target/profiling/{binary}
 ```
 
-## API
+## Public API
 
-#### The `samply_marker!` macro
+### The [`samply_marker!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_marker.html) macro
 
-The [`samply_marker!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_marker.html) macro is the foundational way to emit profiler markers. It creates and emits a [`SamplyMarker`](https://docs.rs/samply-markers/latest/samply_markers/marker/struct.SamplyMarker.html) at the current location in your code, supporting both instant markers (a single point in time) and interval markers (a span of time).
+The [`samply_marker!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_marker.html) macro is the foundational way to emit profiler markers.
+It creates and emits a [`SamplyMarker`](https://docs.rs/samply-markers/latest/samply_markers/marker/struct.SamplyMarker.html) at the current location in your code,
+supporting both instant markers (a single point in time) and interval markers (a span of time).
 
-**Instant Marker**
+#### Instant Marker
 
 An instant marker marks a specific point in time:
 
@@ -62,11 +94,11 @@ fn process_request(request_id: u32) {
     // Emit an instant marker at this exact moment
     samply_marker!({ name: format!("processing request {request_id}") });
 
-    // ... process the request
+    // ... process the request.
 }
 ```
 
-**Interval Marker**
+#### Interval Marker
 
 An interval marker spans from a start time to the current time using [`SamplyTimestamp`](https://docs.rs/samply-markers/latest/samply_markers/marker/struct.SamplyTimestamp.html):
 
@@ -76,10 +108,10 @@ use samply_markers::prelude::*;
 fn query_database(query: &str) -> Vec<String> {
     let start = SamplyTimestamp::now();
 
-    // ... execute the database query
-    let results = vec![]; // Placeholder for actual results
+    // ... execute the database query.
+    let results = vec![]; // Placeholder for actual results.
 
-    // Emit an interval marker from start to now
+    // Emit an interval marker from start to now.
     samply_marker!({
         name: format!("database query: {query}"),
         start_time: start,
@@ -91,69 +123,80 @@ fn query_database(query: &str) -> Vec<String> {
 
 ---
 
-#### The `samply_interval!` macro
+### The [`samply_timer!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_timer.html) macro
 
-While `samply_marker!` requires manually capturing a [`SamplyTimestamp`](https://docs.rs/samply-markers/latest/samply_markers/marker/struct.SamplyTimestamp.html) for interval markers, the [`samply_interval!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_interval.html) macro simplifies this pattern by wrapping the timestamp in a scoped RAII object. It creates a [`SamplyInterval`](https://docs.rs/samply-markers/latest/samply_markers/marker/struct.SamplyInterval.html) that captures the start time when created and automatically emits the interval marker when dropped at the end of its scope.
+While [`samply_marker!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_marker.html) requires manually providing a
+[`SamplyTimestamp`](https://docs.rs/samply-markers/latest/samply_markers/marker/struct.SamplyTimestamp.html) for interval markers,
+the [`samply_timer!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_timer.html) macro simplifies this pattern
+by wrapping the timestamp in a scoped RAII object. It creates a [`SamplyTimer`](https://docs.rs/samply-markers/latest/samply_markers/marker/struct.SamplyTimer.html)
+that registers the time it was created and automatically emits the interval marker when dropped at the end of its scope.
 
-**Automatic Interval**
+#### Automatic Interval
 
-The interval emits when the variable is dropped:
+The interval marker emits when the timer is dropped:
 
 ```rust
 use samply_markers::prelude::*;
 
 fn expensive_computation() {
-    let _timer = samply_interval!({ name: "expensive computation" });
+    let _timer = samply_timer!({ name: "expensive computation" });
 
-    // ... perform expensive work
+    // ... perform expensive work.
 
-    // The interval is automatically emitted here when _timer is dropped
+    // The interval marker is automatically emitted here when _timer is dropped.
 }
 ```
 
-**Early Emit**
+#### Early Emit
 
-You can explicitly emit the interval before the end of the scope:
+You can explicitly emit the interval marker before the end of the scope:
 
 ```rust
 use samply_markers::prelude::*;
 
 fn process_with_cleanup() {
-    let timer = samply_interval!({ name: "core processing" });
+    let timer = samply_timer!({ name: "core processing" });
 
-    // ... perform core processing work
+    // ... perform core processing work.
 
-    // Emit the interval now, excluding cleanup from the measurement
+    // Emit the interval marker now, excluding cleanup from the measurement.
     timer.emit();
 
-    // ... perform cleanup tasks (not included in the interval)
+    // ... perform cleanup tasks (not included in the interval marker).
 
-    // The interval will not emit a second time when dropped
+    // The interval marker will not emit a second time when dropped.
 }
 ```
 
 ---
 
-#### The `samply_measure!` macro
+### The [`samply_measure!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_measure.html) macro
+
+Building on the scoped approach of [`samply_timer!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_timer.html),
+the [`samply_measure!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_measure.html) macro further simplifies profiling
+by eliminating the need to create a scoped timer yourself. Instead, you wrap a code block, then its execution time is automatically measured with an interval marker.
 
-Building on the scoped approach of `samply_interval!`, the [`samply_measure!`](https://docs.rs/samply-markers/latest/samply_markers/macro.samply_measure.html) macro further simplifies profiling by eliminating the need to create a scoped object yourself. Instead, you wrap a code block, and the macro measures its execution time and emits an interval marker, while preserving the block's return value.
+#### Synchronous Example
 
-**Synchronous Example**
+The value of the block expression is returned:
 
 ```rust
 use samply_markers::prelude::*;
 
-fn compute_fibonacci(n: u32) -> u64 {
+fn compute_sum(values: &[i32]) -> i32 {
     samply_measure!({
-        // ... compute fibonacci
-        42 // Return value is preserved
+        values.iter().sum()
     }, marker: {
-        name: format!("fibonacci({n})"),
+        name: "compute sum",
     })
 }
+
+let values = vec![1, 2, 3, 4, 5];
+let result = compute_sum(&values);
+assert_eq!(result, 15);
 ```
 
-**With `?` Operator**
+#### With `?` Operator
 
 The block's control flow is preserved, including early returns:
 
@@ -162,12 +205,12 @@ use samply_markers::prelude::*;
 
 fn parse_and_validate(data: &str) -> Result<u32, String> {
     samply_measure!({
-        // The ? operator works normally and returns from the function
+        // The ? operator works normally and returns from the function.
         let parsed = data.parse::<u32>()
             .map_err(|e| format!("parse error: {e}"))?;
 
         if parsed > 100 {
-            return Err("value too large".to_string());
+            return Err(String::from("value too large"));
         }
 
         Ok(parsed)
@@ -177,7 +220,7 @@ fn parse_and_validate(data: &str) -> Result<u32, String> {
 }
 ```
 
-**Asynchronous Example**
+#### Asynchronous Example
 
 For async code, use `async` before the block and `.await` after the macro:
 
@@ -186,22 +229,28 @@ use samply_markers::prelude::*;
 
 async fn process_data(data_id: u64) -> Result<String, String> {
     let result = samply_measure!(async {
-        // The async block is measured from start to completion
+        // The async block is measured from start to completion.
         let data = simulate_async_work().await?;
         let processed = format!("Processed: {data} (id: {data_id})");
         Ok(processed)
     }, marker: {
         name: format!("process data {data_id}"),
     })
-    .await?; // Don't forget the .await after the macro
+    .await?;
 
     Ok(result)
 }
 ```
 
 ## Examples
 
-Here's a complete example demonstrating all three macros in context:
+Example profiles of the code below:
+
+* [Ubuntu](https://share.firefox.dev/4qZ7yUj)
+* [macOS](https://share.firefox.dev/49Au7J1)
+* Windows (not yet supported)
+
+Here's a complete example demonstrating everything in context:
 
 ```rust
 use samply_markers::prelude::*;
@@ -232,9 +281,9 @@ async fn fetch_url(url: &str) -> (String, Option<String>) {
 
 #[tokio::main]
 async fn main() {
-    // Create an interval marker that will span the entirety of main()
-    // The marker will emit when it is dropped at the end of the scope.
-    let _main_interval = samply_interval!({ name: "main()" });
+    // Create a timer that will span the entirety of main().
+    // The timer will emit an interval marker when it is dropped at the end of the scope.
+    let _main_timer = samply_timer!({ name: "main()" });
 
     println!("\nStarting samply-markers demo...\n");
 
@@ -279,10 +328,4 @@ async fn main() {
 }
 ```
 
-## Example Profiles
-
-* [Ubuntu](https://share.firefox.dev/3LCG4DQ)
-* [macOS](https://share.firefox.dev/47SmHOr)
-* Windows is not yet supported.
-
 [samply]: https://github.com/mstange/samply?tab=readme-ov-file#samply