Dotnet-api-docs: DispatcherTimer ctor does not indicate that Start will be called automatically

[BhaaLseN]

The DispatcherTimer(TimeSpan, DispatcherPriority, EventHandler, Dispatcher) Constructor automatically starts/enables the instance, and neither IntelliSense nor the documentation indicate that this is the case.
We were wondering why the code behaved differently, thinking this was only a short-hand form of specifying all parameters at once (vs. attaching the EventHandler using += afterwards); but looking at the source revealed that it actually calls Start.

I have no idea how to express this concisely, otherwise I'd have opened a pull request right away.

Other than adding this note to the summary (which I believe should be done to make it clear in IntelliSense inside VS right away), it might be a good idea to provide an example on when this would be useful (or could be used over the other alternatives), or at least a remark highlighting this distinction.

[mairaw]

Thanks for your feedback @BhaaLseN. Can you comment on this @Tanya-Solyanik? Is that the only constructor that does this? Is this by design?

[Tanya-Solyanik]

@AlexGhiondea - Who owns DispatcherTimer?

[rladuca]

@mairaw DispatcherTimer is owned by WPF. This is, indeed, the only constructor that explicitly starts the timer and we should have appropriate documentation to that affect.

The code comments are slightly different but still somewhat ambiguous:

        /// <summary>
        ///     Creates a timer that is bound to the specified dispatcher and
        ///     will be processed at the specified priority, after the
        ///     specified timeout.
        /// </summary>

I could interpret "will be processed" as "will be started", but the better idea would be to take the current blurb in the documentation and changing it to read:

Initializes a new instance of the DispatcherTimer class which uses the specified time interval, priority, event handler, and Dispatcher, then calls Start()

Where Start is a link to the public function in DispatcherTimer.

[eiriktsarpalis]

Tagging @gomathip02 @vatsan-madhavan who might be able to triage this.

[rladuca]

@eiriktsarpalis:

@ryalanms @SamBent or @fabiant3 are more appropriate at this time.

[SamBent]

On behalf of WPF team, I endorse Rob's suggestion.

I don't like the Oxford comma "... event handler, and Dispatcher...", but style and grammar are doc team's call.

[mairaw]

Oxford comma is Microsoft's style 😉
https://docs.microsoft.com/en-us/style-guide/punctuation/commas

I'd also change that slightly a bit
"Initializes a new instance of the DispatcherTimer class that uses the specified time interval, priority, event handler, and Dispatcher, and then calls Start()"

[SamBent]

Even better. I was more bothered by two commas near each other but in different roles, not so much that one of them was Oxford. Your suggestion addresses that better than mine.