Make the PeriodicTimer.WaitForNextTickAsync description more descriptive #119637
+8
−1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR improves the documentation for the PeriodicTimer.WaitForNextTickAsync method by clarifying the boolean return value semantics and the different completion states of the returned ValueTask.
Key Changes
- Enhanced the XML documentation to explicitly describe when the method returns
truevsfalse - Added clarification about the cancellation behavior and task state
github-actions
bot
added
the
needs-area-label
dotnet-policy-service
bot
added
the
community-contribution
jkotas
added
area-System.Threading
documentation
Contributor
|
Tagging subscribers to this area: @mangod9 |
eduardo-vp
reviewed
Nov 4, 2025
Comment on lines
128
to
133
| /// <returns>A <see cref="ValueTask" /> that will be completed due to the timer firing (in which case the result is <c>true</c>), <see cref="Dispose"/> being called to stop the timer (in which case the result is <c>false</c>), or cancellation being requested (in which case the task enters the Canceled state).</returns> | ||
| /// <remarks> | ||
| /// The <see cref="PeriodicTimer"/> behaves like an auto-reset event, in that multiple ticks are coalesced into a single tick if they occur between | ||
| /// calls to <see cref="WaitForNextTickAsync"/>. Similarly, a call to <see cref="Dispose"/> will void any tick not yet consumed. <see cref="WaitForNextTickAsync"/> | ||
| /// may only be used by one consumer at a time, and may be used concurrently with a single call to <see cref="Dispose"/>. | ||
| /// </remarks> |
Member
There was a problem hiding this comment.
I think it makes sense to include more descriptive information of the returning ValueTask but including it in the returns section is not consistent with the repository. How about
Suggested change
| /// <returns>A <see cref="ValueTask" /> that will be completed due to the timer firing, <see cref="Dispose"/> being called to stop the timer, or cancellation being requested.</returns> | |
| /// <remarks> | |
| /// The value of the Result property of the returned <see cref="ValueTask" /> is <see langword="true"/> when it's completed due to the timer firing and | |
| /// <see langword="false"/> when the timer is disposed or stopped. | |
| /// A cancelled task is returned if cancellation is requested. | |
| /// The <see cref="PeriodicTimer"/> behaves like an auto-reset event, in that multiple ticks are coalesced into a single tick if they occur between | |
| /// calls to <see cref="WaitForNextTickAsync"/>. Similarly, a call to <see cref="Dispose"/> will void any tick not yet consumed. <see cref="WaitForNextTickAsync"/> | |
| /// may only be used by one consumer at a time, and may be used concurrently with a single call to <see cref="Dispose"/>. | |
| /// </remarks> |
Contributor
Author
There was a problem hiding this comment.
(I've adjusted the cancellation line because it's not precise.)
Smaug123
force-pushed
the
improve-periodictimer-description
branch
from
9386b6f to
6f4c619
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The current documentation doesn't actually say what the semantics of the result are.