Skip to content

The documentation is wrong for Timer.Change method #3762

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 2, 2020
Merged

The documentation is wrong for Timer.Change method #3762

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c6c99a2
The documentation is wrong for Timer.Change method
brendansensus Jan 10, 2020
b293e06
Update xml/System.Threading/Timer.xml
brendansensus Jan 29, 2020
e738b2f
Update xml/System.Threading/Timer.xml
brendansensus Jan 29, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions xml/System.Threading/Timer.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -594,7 +594,7 @@ Sub TimerCallback(state As Object)
<Parameter Name="period" Type="System.Int64" Index="1" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-2.0;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0;netstandard-2.1;netcore-3.1" />
</Parameters>
<Docs>
<param name="dueTime">The amount of time to delay before the invoking the callback method specified when the <see cref="T:System.Threading.Timer" /> was constructed, in milliseconds. Specify <see cref="F:System.Threading.Timeout.Infinite" /> to prevent the timer from restarting. Specify zero (0) to restart the timer immediately.</param>
<param name="dueTime">The amount of time to delay before the invoking the callback method specified when the <see cref="T:System.Threading.Timer" /> was constructed, in milliseconds. Specify <see cref="F:System.Threading.Timeout.Infinite" /> to prevent the timer from restarting. Specify zero (0) to restart the timer immediately. This value must be less than or equal to 4294967294.</param>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we fix the exception being thrown, do you think it's still useful to mention the max value here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think its still useful to mention the max value in the "dueTime" parameter documentation here. It would probably be good to add the same information on the max value when describing the "period" parameter as well. Not everyone reads all the documentation on the exceptions. I think it makes sense to have information on maximum values when you are describing the parameters. I also looked at your other suggestions above, and they look fine.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good. I agree we should do the same for both parameters then. Can you please apply my suggestions above using the Commit suggestion button?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I will commit the suggestions now. Wasn't sure if I was supposed to do that as part of the process.

<param name="period">The time interval between invocations of the callback method specified when the <see cref="T:System.Threading.Timer" /> was constructed, in milliseconds. Specify <see cref="F:System.Threading.Timeout.Infinite" /> to disable periodic signaling.</param>
<summary>Changes the start time and the interval between method invocations for a timer, using 64-bit signed integers to measure time intervals.</summary>
<returns>
Expand All @@ -614,8 +614,8 @@ Sub TimerCallback(state As Object)
]]></format>
</remarks>
<exception cref="T:System.ObjectDisposedException">The <see cref="T:System.Threading.Timer" /> has already been disposed.</exception>
<exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="dueTime" /> or <paramref name="period" /> parameter is less than -1.</exception>
<exception cref="T:System.NotSupportedException">The <paramref name="dueTime" /> or <paramref name="period" /> parameter is greater than 4294967294.</exception>
<exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="dueTime" /> or <paramref name="period" /> parameter is less than -1 or <paramref name="dueTime" /> is greater than 4294967294.</exception>
<exception cref="T:System.NotSupportedException">The <paramref name="period" /> parameter is greater than 4294967294.</exception>
<related type="Article" href="~/docs/standard/threading/timers.md">Timers</related>
</Docs>
</Member>
Expand Down