`PeriodicTimer.WaitForNextTickAsync`: Describe meaning of returned `bool` values

[scottmcm]

Type of issue

Missing information

Description

The return value for WaitForNextTickAsync is a ValueTask<bool>, but the documentation doesn't say what true or false mean as the value of that task, only when the task will be completed.

I would expect to see something like

The task will have value true when running normally, or false when the timer has been stopped.

And maybe an example showing a

while (await timer.WaitForNextTick()) {
    // ... do work ...
}

loop as the canonical way to consume the timer. (Well, if that's right -- I don't know.)

But having a "see also" (cc #7451 (comment)) to an article about how to use PeriodicTimer instead of an example would also be fine. (There's no example on the class-level documentation page either.)

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.threading.periodictimer.waitfornexttickasync?view=net-8.0#system-threading-periodictimer-waitfornexttickasync(system-threading-cancellationtoken)

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Threading/PeriodicTimer.xml

Document Version Independent Id

0ef31de4-0c6b-4ae5-b172-c2e89beee4cc

Article author

@dotnet-bot

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-threading-tasks