- Notifications
You must be signed in to change notification settings - Fork1.6k
Summary: Event related
The following table provides wording guidelines and boilerplate text for Summary sections in event and event-related class pages.
| Item | Wording | Examples |
|---|---|---|
| Event | Occurs when<condition>. | Click event summary: Occurs when the user clicks the control. |
| <EventArgs> class | Provides data for the<Event> event. | ComponentRenameEventArgsclass summary: Provides data for theComponentRename event. |
| Event-handler delegate class, specific to one event on a control | Represents the callback method that will handle the<Event> event of a<Class>. | PeekCompletedEventHandlerdelegate summary: Represents the callback method that will handle thePeekCompleted event of aMessageQueue. |
| Event-handler delegate class, specific to multiple events on a control | Represents the callback method that will handle the<Event1> event,<Event2> event, or<Event3> event of a<Class>. | PrintEventHandlerdelegate summary: Represents the callback method that will handle theBeginPrint event orEndPrint event of aPrintDocument. |
| Event-handler delegate class, specific to one event on multiple controls | Represents the callback method that will handle the<Event> event of a<Class1> or a<Class2>. | MeasureItemEventHandlerdelegate summary: Represents the callback method that will handle theMeasureItem event of aListBox,ComboBox,CheckedListBox, orMenuItem control. |
| Event-handler delegate class, generic | Represents the callback method that will handle an event of a control. | EventHandler Genericdelegate summary Represents the callback method that will handle the event. |
| On<Event> method* | Raises the<Event> event. | Control.OnBackgroundImageChangedmethod summary: Raises theBackgroundImageChanged event. |
*Note:In some cases, such as theWebPart class, a method namedOnEventName might not raise theEventName event. For example,WebPart defines four methods namedOnClosing,OnConnectModeChanged,OnDeleting, andOnEditModeChanged. Derived classes override these methods and provide special handling for the state transitions named by the methods. Thus, the description of theOnClosing method reads, "Enables derived classes to provide custom handling when aWebPart control is closed on a Web Parts page." The phrase in italics is the appropriate pattern for such summaries.
Because this naming pattern violates .NET naming guidelines, the writer should raise the naming issue in the design phase, if the opportunity arises. A name such asClosingNotification orClosingCallback would be more appropriate in this scenario.
Other special cases in WPF and Silverlight content use either "Provides class handling for theEventName routed event" or "Called before theEventName event occurs" for the summary.