Potentially misleading descriptions on methods of TimeSpan struct - by Anthony W Pegram

Status : 

  Fixed<br /><br />
		This item has been fixed in the current or upcoming version of this product.<br /><br />
		A more detailed explanation for the resolution of this particular item may have been provided in the comments section.

Sign in
to vote
ID 599964 Comments
Status Closed Workarounds
Type Suggestion Repros 0
Opened 9/16/2010 9:23:38 PM
Access Restriction Public


See: http://stackoverflow.com/questions/3732553/is-there-a-bug-in-timespan

The TimeSpan methods return new instances of TimeSpan rather than modifying the value of the original struct. This is accepted behavior. However, the wording on the methods could be interpreted by those not familiar with immutable structs to mean that the original instance would be modified. For example, the description in intellisense for TimeSpan.Add is "Adds the specified System.TimeSpan to this instance." If I didn't know any better, I would think *this instance* would be modified. I believe a better wording for such methods would be something along the lines of "Returns the result of the specified System.TimeSpan added to this instance."
Sign in to post a comment.
Posted by Microsoft on 9/28/2010 at 10:12 AM

This general issue -- the failure to explicitly note that a method returns a new TimeSpan object in the method description -- affects the TimeSpan.Negate and TimeSpan.Subtract methods in addition to the TimeSpan.Add method. We've modified the description of each to make it clear that the method returns a new TimeSpan object. A fourth method, TimeSpan.Duration, already noted that the the return value was a new TimeSpan object. The updated version of the documentation should appear in the online version of the documentation in the near future.

Thanks for pointing this out to us.

--Ron Petrusha
CLR Developer Content Team
Microsoft Corporation
Posted by Microsoft on 9/17/2010 at 2:00 AM
Thank you for your feedback, We are currently reviewing the issue you have submitted. If this issue is urgent, please contact support directly(http://support.microsoft.com)