docs: add code docs as markdown

Author: egil

README.md

@@ -17,47 +17,24 @@ This describes how to get started:
 
 2. Take a dependency on `TimeProvider` in your code. Inject the production version of `TimeProvider` available via the [`TimeProvider.System`](https://learn.microsoft.com/en-us/dotnet/api/system.timeprovider.system?#system-timeprovider-system) property during production.
 
-3. During testing, inject the `ManualTimeProvider` from this library. With `ManualTimeProvider`, you can move advance time by calling `Advance(TimeSpan)` or `SetUtcNow(DateTimeOffset)` and jump ahead in time using `Jump(TimeSpan)` or `Jump(DateTimeOffset)`. This allows you to write tests that run fast and predictably, even if the system under test pauses execution for multiple minutes using e.g. `TimeProvider.Delay(TimeSpan)`, the replacement for `Task.Delay(TimeSpan)`.
+3. During testing, inject the `ManualTimeProvider` from this library. This allows you to write tests that run fast and predictably.
+   - Advance time by calling `Advance(TimeSpan)` or `SetUtcNow(DateTimeOffset)` or
+   - Jump ahead in time using `Jump(TimeSpan)` or `Jump(DateTimeOffset)`     
 
-Read the rest of this README for further details and examples.
+4. See the **[`ManualTimeProvider API`](https://github.com/egil/TimeProviderExtensions/blob/main/docs/TimeProviderExtensions.ManualTimeProvider.md) page** for the full API documentation for `ManualTimeProvider`.
 
-## ManualTimeProvider API
+5. Read the rest of this README for further details and examples.
 
-The ManualTimeProvider represents a synthetic time provider that can be used to enable deterministic behavior in tests.
+## API Overview
 
-## Difference between `ManualTimeProvider` and `FakeTimeProvider`
-
-The .NET team has published a similar test-specific time provider, the [`Microsoft.Extensions.Time.Testing.FakeTimeProvider`](https://www.nuget.org/packages/Microsoft.Extensions.Time.Testing.FakeTimeProvider/).
-
-The public API of both `FakeTimeProvider` and `ManualTimeProvider` are compatible, but there are some differences in when time is set before timer callbacks. Let's illustrate this with an example:
-
-For example, if we create an `ITimer` with a *due time* and *period* set to **1 second**, the `DateTimeOffset` returned from `GetUtcNow()` during the timer callback may be different depending on the amount passed to `Advance()` (or `SetUtcNow()`).
-
-If we call `Advance(TimeSpan.FromSeconds(1))` three times, effectively moving time forward by three seconds, the timer callback will be invoked once at times `00:01`, `00:02`, and `00:03`, as illustrated in the drawing below. Both `FakeTimeProvider` and `ManualTimeProvider` behave like this:
-
-![Advancing time by three seconds in one-second increments.](https://raw.githubusercontent.com/egil/TimeProviderExtensions/main/docs/advance-1-second.svg)
-
-If we instead call `Advance(TimeSpan.FromSeconds(3))` once, the two implementations behave differently. `ManualTimeProvider` will invoke the timer callback at the same time (`00:01`, `00:02`, and `00:03`) as if we had called `Advance(TimeSpan.FromSeconds(1))` three times, as illustrated in the drawing below:
-
-![Advancing time by three seconds in one step using ManualTimeProvider.](https://raw.githubusercontent.com/egil/TimeProviderExtensions/main/docs/ManualTimeProvider-advance-3-seconds.svg)
-
-However, `FakeTimeProvider` will invoke the timer callback at time `00:03` three times, as illustrated in the drawings below:
-
-![Advancing time by three seconds in one step using FakeTimeProvider.](https://raw.githubusercontent.com/egil/TimeProviderExtensions/main/docs/FakeTimeProvider-advance-3-seconds.svg)
-
-Technically, both implementations are correct since the `ITimer` abstractions only promise to invoke the callback timer *on or after the due time/period has elapsed*, never before.
-
-However, I strongly prefer the `ManualTimeProvider` approach since it behaves consistently independent of how time is moved forward. It seems much more in the spirit of how a deterministic time provider should behave and avoids users being surprised when writing tests. I imagine users may get stuck for a while trying to debug why the time reported by `GetUtcNow()` is not set as expected due to the subtle difference in the behavior of `FakeTimeProvider`.
-
-That said, it can be useful to test that your code behaves correctly if a timer isn't allocated processor time immediately when it's callback should fire, and for that, `ManualTimeProvider` includes a different method, `Jump`.
-
-### Jumping to a point in time
+These pages has all the details of the API included in this package:
 
-A real `ITimer`'s callback may not be allocated processor time and be able to fire at the moment it has been scheduled, e.g. if the processor is busy doing other things. The callback will eventually fire (unless the timer is disposed of).
+- [`ManualTimeProvider`](https://github.com/egil/TimeProviderExtensions/blob/main/docs/TimeProviderExtensions.ManualTimeProvider.md)
 
-To support testing this scenario, `ManualtTimeProvider` includes a method that will jump time to a specific point, and then invoke all scheduled timer callbacks between the start and end of the jump. This behavior is similar to how `FakeTimeProvider`s `Advance` method works, as described in the previous section.
+**.NET 7 and earlier:**
 
-![Jumping ahead in time by three seconds in one step using ManualTimeProvider.](https://raw.githubusercontent.com/egil/TimeProviderExtensions/main/docs/jump-3-seconds.svg)
+- [`PeriodicTimerWrapper`](https://github.com/egil/TimeProviderExtensions/blob/main/docs/System.Threading.PeriodicTimerWrapper.md)
+- [`TimeProviderPeriodicTimerExtensions`](https://github.com/egil/TimeProviderExtensions/blob/main/docs/System.Threading.TimeProviderPeriodicTimerExtensions.md)
 
 ## Known limitations and issues:
 
@@ -216,3 +193,37 @@ public async Task DoStuff_does_stuff_every_11_seconds()
     .BeCloseTo(DateTimeOffset.UtcNow, precision: TimeSpan.FromMilliseconds(50));
 }
 ```
+
+## Difference between `ManualTimeProvider` and `FakeTimeProvider`
+
+The .NET team has published a similar test-specific time provider, the [`Microsoft.Extensions.Time.Testing.FakeTimeProvider`](https://www.nuget.org/packages/Microsoft.Extensions.Time.Testing.FakeTimeProvider/).
+
+The public API of both `FakeTimeProvider` and `ManualTimeProvider` are compatible, but there are some differences in when time is set before timer callbacks. Let's illustrate this with an example:
+
+For example, if we create an `ITimer` with a *due time* and *period* set to **1 second**, the `DateTimeOffset` returned from `GetUtcNow()` during the timer callback may be different depending on the amount passed to `Advance()` (or `SetUtcNow()`).
+
+If we call `Advance(TimeSpan.FromSeconds(1))` three times, effectively moving time forward by three seconds, the timer callback will be invoked once at times `00:01`, `00:02`, and `00:03`, as illustrated in the drawing below. Both `FakeTimeProvider` and `ManualTimeProvider` behave like this:
+
+![Advancing time by three seconds in one-second increments.](https://raw.githubusercontent.com/egil/TimeProviderExtensions/main/docs/advance-1-second.svg)
+
+If we instead call `Advance(TimeSpan.FromSeconds(3))` once, the two implementations behave differently. `ManualTimeProvider` will invoke the timer callback at the same time (`00:01`, `00:02`, and `00:03`) as if we had called `Advance(TimeSpan.FromSeconds(1))` three times, as illustrated in the drawing below:
+
+![Advancing time by three seconds in one step using ManualTimeProvider.](https://raw.githubusercontent.com/egil/TimeProviderExtensions/main/docs/ManualTimeProvider-advance-3-seconds.svg)
+
+However, `FakeTimeProvider` will invoke the timer callback at time `00:03` three times, as illustrated in the drawings below:
+
+![Advancing time by three seconds in one step using FakeTimeProvider.](https://raw.githubusercontent.com/egil/TimeProviderExtensions/main/docs/FakeTimeProvider-advance-3-seconds.svg)
+
+Technically, both implementations are correct since the `ITimer` abstractions only promise to invoke the callback timer *on or after the due time/period has elapsed*, never before.
+
+However, I strongly prefer the `ManualTimeProvider` approach since it behaves consistently independent of how time is moved forward. It seems much more in the spirit of how a deterministic time provider should behave and avoids users being surprised when writing tests. I imagine users may get stuck for a while trying to debug why the time reported by `GetUtcNow()` is not set as expected due to the subtle difference in the behavior of `FakeTimeProvider`.
+
+That said, it can be useful to test that your code behaves correctly if a timer isn't allocated processor time immediately when it's callback should fire, and for that, `ManualTimeProvider` includes a different method, `Jump`.
+
+### Jumping to a point in time
+
+A real `ITimer`'s callback may not be allocated processor time and be able to fire at the moment it has been scheduled, e.g. if the processor is busy doing other things. The callback will eventually fire (unless the timer is disposed of).
+
+To support testing this scenario, `ManualtTimeProvider` includes a method that will jump time to a specific point, and then invoke all scheduled timer callbacks between the start and end of the jump. This behavior is similar to how `FakeTimeProvider`s `Advance` method works, as described in the previous section.
+
+![Jumping ahead in time by three seconds in one step using ManualTimeProvider.](https://raw.githubusercontent.com/egil/TimeProviderExtensions/main/docs/jump-3-seconds.svg)

docs/System.Threading.PeriodicTimerWrapper.md

@@ -0,0 +1,91 @@
+#### [TimeProviderExtensions](index.md 'index')
+### [System.Threading](index.md#System.Threading 'System.Threading')
+
+## PeriodicTimerWrapper Class
+
+Provides a lightweight wrapper around a [System.Threading.PeriodicTimer](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.PeriodicTimer 'System.Threading.PeriodicTimer') to enable controlling the timer via a [System.TimeProvider](https://docs.microsoft.com/en-us/dotnet/api/System.TimeProvider 'System.TimeProvider').
+A periodic timer enables waiting asynchronously for timer ticks.
+
+```csharp
+public abstract class PeriodicTimerWrapper :
+System.IDisposable
+```
+
+Inheritance [System.Object](https://docs.microsoft.com/en-us/dotnet/api/System.Object 'System.Object') 🡒 PeriodicTimerWrapper
+
+Implements [System.IDisposable](https://docs.microsoft.com/en-us/dotnet/api/System.IDisposable 'System.IDisposable')
+
+### Remarks
+
+This timer is intended to be used only by a single consumer at a time: only one call to [WaitForNextTickAsync(CancellationToken)](System.Threading.PeriodicTimerWrapper.md#System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken) 'System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken)')
+may be in flight at any given moment.  [Dispose()](System.Threading.PeriodicTimerWrapper.md#System.Threading.PeriodicTimerWrapper.Dispose() 'System.Threading.PeriodicTimerWrapper.Dispose()') may be used concurrently with an active [WaitForNextTickAsync(CancellationToken)](System.Threading.PeriodicTimerWrapper.md#System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken) 'System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken)')
+to interrupt it and cause it to return false.
+### Methods
+
+<a name='System.Threading.PeriodicTimerWrapper.~PeriodicTimerWrapper()'></a>
+
+## PeriodicTimerWrapper.~PeriodicTimerWrapper() Method
+
+Ensures that resources are freed and other cleanup operations are performed when the garbage collector reclaims the [System.Threading.PeriodicTimer](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.PeriodicTimer 'System.Threading.PeriodicTimer') object.
+
+```csharp
+~PeriodicTimerWrapper();
+```
+
+<a name='System.Threading.PeriodicTimerWrapper.Dispose()'></a>
+
+## PeriodicTimerWrapper.Dispose() Method
+
+Stops the timer and releases associated managed resources.
+
+```csharp
+public void Dispose();
+```
+
+Implements [Dispose()](https://docs.microsoft.com/en-us/dotnet/api/System.IDisposable.Dispose 'System.IDisposable.Dispose')
+
+### Remarks
+[Dispose()](System.Threading.PeriodicTimerWrapper.md#System.Threading.PeriodicTimerWrapper.Dispose() 'System.Threading.PeriodicTimerWrapper.Dispose()') will cause an active wait with [WaitForNextTickAsync(CancellationToken)](System.Threading.PeriodicTimerWrapper.md#System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken) 'System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken)') to complete with a value of false.
+            All subsequent [WaitForNextTickAsync(CancellationToken)](System.Threading.PeriodicTimerWrapper.md#System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken) 'System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken)') invocations will produce a value of false.
+
+<a name='System.Threading.PeriodicTimerWrapper.Dispose(bool)'></a>
+
+## PeriodicTimerWrapper.Dispose(bool) Method
+
+Dispose of the wrapped [System.Threading.PeriodicTimer](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.PeriodicTimer 'System.Threading.PeriodicTimer').
+
+```csharp
+protected abstract void Dispose(bool disposing);
+```
+#### Parameters
+
+<a name='System.Threading.PeriodicTimerWrapper.Dispose(bool).disposing'></a>
+
+`disposing` [System.Boolean](https://docs.microsoft.com/en-us/dotnet/api/System.Boolean 'System.Boolean')
+
+<a name='System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken)'></a>
+
+## PeriodicTimerWrapper.WaitForNextTickAsync(CancellationToken) Method
+
+Wait for the next tick of the timer, or for the timer to be stopped.
+
+```csharp
+public abstract System.Threading.Tasks.ValueTask<bool> WaitForNextTickAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
+```
+#### Parameters
+
+<a name='System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken).cancellationToken'></a>
+
+`cancellationToken` [System.Threading.CancellationToken](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.CancellationToken 'System.Threading.CancellationToken')
+
+A [System.Threading.CancellationToken](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.CancellationToken 'System.Threading.CancellationToken') to use to cancel the asynchronous wait. If cancellation is requested, it affects only the single wait operation;
+the underlying timer continues firing.
+
+#### Returns
+[System.Threading.Tasks.ValueTask&lt;](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.ValueTask-1 'System.Threading.Tasks.ValueTask`1')[System.Boolean](https://docs.microsoft.com/en-us/dotnet/api/System.Boolean 'System.Boolean')[&gt;](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.ValueTask-1 'System.Threading.Tasks.ValueTask`1')  
+A task that will be completed due to the timer firing, [Dispose()](System.Threading.PeriodicTimerWrapper.md#System.Threading.PeriodicTimerWrapper.Dispose() 'System.Threading.PeriodicTimerWrapper.Dispose()') being called to stop the timer, or cancellation being requested.
+
+### Remarks
+The [System.Threading.PeriodicTimer](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.PeriodicTimer 'System.Threading.PeriodicTimer') behaves like an auto-reset event, in that multiple ticks are coalesced into a single tick if they occur between
+calls to [WaitForNextTickAsync(CancellationToken)](System.Threading.PeriodicTimerWrapper.md#System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken) 'System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken)').  Similarly, a call to [Dispose()](System.Threading.PeriodicTimerWrapper.md#System.Threading.PeriodicTimerWrapper.Dispose() 'System.Threading.PeriodicTimerWrapper.Dispose()') will void any tick not yet consumed. [WaitForNextTickAsync(CancellationToken)](System.Threading.PeriodicTimerWrapper.md#System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken) 'System.Threading.PeriodicTimerWrapper.WaitForNextTickAsync(System.Threading.CancellationToken)')
+may only be used by one consumer at a time, and may be used concurrently with a single call to [Dispose()](System.Threading.PeriodicTimerWrapper.md#System.Threading.PeriodicTimerWrapper.Dispose() 'System.Threading.PeriodicTimerWrapper.Dispose()').

docs/System.Threading.TimeProviderPeriodicTimerExtensions.md

@@ -0,0 +1,44 @@
+#### [TimeProviderExtensions](index.md 'index')
+### [System.Threading](index.md#System.Threading 'System.Threading')
+
+## TimeProviderPeriodicTimerExtensions Class
+
+PeriodicTimer extensions for [System.TimeProvider](https://docs.microsoft.com/en-us/dotnet/api/System.TimeProvider 'System.TimeProvider').
+
+```csharp
+public static class TimeProviderPeriodicTimerExtensions
+```
+
+Inheritance [System.Object](https://docs.microsoft.com/en-us/dotnet/api/System.Object 'System.Object') 🡒 TimeProviderPeriodicTimerExtensions
+### Methods
+
+<a name='System.Threading.TimeProviderPeriodicTimerExtensions.CreatePeriodicTimer(thisSystem.TimeProvider,System.TimeSpan)'></a>
+
+## TimeProviderPeriodicTimerExtensions.CreatePeriodicTimer(this TimeProvider, TimeSpan) Method
+
+Factory method that creates a periodic timer that enables waiting asynchronously for timer ticks.
+Use this factory method as a replacement for instantiating a [System.Threading.PeriodicTimer](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.PeriodicTimer 'System.Threading.PeriodicTimer').
+
+```csharp
+public static System.Threading.PeriodicTimerWrapper CreatePeriodicTimer(this System.TimeProvider timeProvider, System.TimeSpan period);
+```
+#### Parameters
+
+<a name='System.Threading.TimeProviderPeriodicTimerExtensions.CreatePeriodicTimer(thisSystem.TimeProvider,System.TimeSpan).timeProvider'></a>
+
+`timeProvider` [System.TimeProvider](https://docs.microsoft.com/en-us/dotnet/api/System.TimeProvider 'System.TimeProvider')
+
+<a name='System.Threading.TimeProviderPeriodicTimerExtensions.CreatePeriodicTimer(thisSystem.TimeProvider,System.TimeSpan).period'></a>
+
+`period` [System.TimeSpan](https://docs.microsoft.com/en-us/dotnet/api/System.TimeSpan 'System.TimeSpan')
+
+#### Returns
+[PeriodicTimerWrapper](System.Threading.PeriodicTimerWrapper.md 'System.Threading.PeriodicTimerWrapper')  
+A new [PeriodicTimerWrapper](System.Threading.PeriodicTimerWrapper.md 'System.Threading.PeriodicTimerWrapper').
+Note, this is a wrapper around a [System.Threading.PeriodicTimer](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.PeriodicTimer 'System.Threading.PeriodicTimer'),
+and will behave exactly the same as the original.
+
+### Remarks
+This timer is intended to be used only by a single consumer at a time: only one call to [System.Threading.PeriodicTimer.WaitForNextTickAsync(System.Threading.CancellationToken)](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.PeriodicTimer.WaitForNextTickAsync#System_Threading_PeriodicTimer_WaitForNextTickAsync_System_Threading_CancellationToken_ 'System.Threading.PeriodicTimer.WaitForNextTickAsync(System.Threading.CancellationToken)')
+may be in flight at any given moment. [System.Threading.PeriodicTimer.Dispose](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.PeriodicTimer.Dispose 'System.Threading.PeriodicTimer.Dispose') may be used concurrently with an active [System.Threading.PeriodicTimer.WaitForNextTickAsync(System.Threading.CancellationToken)](https://docs.microsoft.com/en-us/dotnet/api/System.Threading.PeriodicTimer.WaitForNextTickAsync#System_Threading_PeriodicTimer_WaitForNextTickAsync_System_Threading_CancellationToken_ 'System.Threading.PeriodicTimer.WaitForNextTickAsync(System.Threading.CancellationToken)')
+to interrupt it and cause it to return false.