Home Dashboard Directory Help
Search

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


Status: 

Closed
 as Fixed Help for as Fixed


2
0
Sign in
to vote
Type: Suggestion
ID: 599964
Opened: 9/16/2010 9:23:38 PM
Access Restriction: Public
0
Workaround(s)
view

Description

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."
Details
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)
Sign in to post a workaround.