Improved inline documentation of class event handler methods (#18869)

src/Avalonia.Base/Input/InputElement.cs

@@ -560,62 +560,83 @@ namespace Avalonia.Input
         /// Called before the <see cref="KeyDown"/> event occurs.
         /// </summary>
         /// <param name="e">The event args.</param>
+        /// <summary>
+        /// Invoked when an unhandled <see cref="KeyDownEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
+        /// </summary>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnKeyDown(KeyEventArgs e)
         {
         }
 
         /// <summary>
-        /// Called before the <see cref="KeyUp"/> event occurs.
+        /// Invoked when an unhandled <see cref="KeyUpEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
         /// </summary>
-        /// <param name="e">The event args.</param>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnKeyUp(KeyEventArgs e)
         {
         }
 
         /// <summary>
-        /// Called before the <see cref="TextInput"/> event occurs.
+        /// Invoked when an unhandled <see cref="TextInputEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
         /// </summary>
-        /// <param name="e">The event args.</param>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnTextInput(TextInputEventArgs e)
         {
         }
 
         /// <summary>
-        /// Called before the <see cref="PointerEntered"/> event occurs.
+        /// Invoked when an unhandled <see cref="PointerEnteredEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
         /// </summary>
-        /// <param name="e">The event args.</param>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnPointerEntered(PointerEventArgs e)
         {
         }
 
         /// <summary>
-        /// Called before the <see cref="PointerExited"/> event occurs.
+        /// Invoked when an unhandled <see cref="PointerExitedEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
         /// </summary>
-        /// <param name="e">The event args.</param>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnPointerExited(PointerEventArgs e)
         {
         }
 
         /// <summary>
-        /// Called before the <see cref="PointerMoved"/> event occurs.
+        /// Invoked when an unhandled <see cref="PointerMovedEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
         /// </summary>
-        /// <param name="e">The event args.</param>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnPointerMoved(PointerEventArgs e)
         {
         }
 
+
         /// <summary>
-        /// Called before the <see cref="PointerPressed"/> event occurs.
+        /// Invoked when an unhandled <see cref="PointerPressedEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
         /// </summary>
-        /// <param name="e">The event args.</param>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnPointerPressed(PointerPressedEventArgs e)
         {
         }
 
         /// <summary>
-        /// Called before the <see cref="PointerReleased"/> event occurs.
+        /// Invoked when an unhandled <see cref="PointerReleasedEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
         /// </summary>
-        /// <param name="e">The event args.</param>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnPointerReleased(PointerReleasedEventArgs e)
         {
         }
@@ -653,18 +674,22 @@ namespace Avalonia.Input
         }
 
         /// <summary>
-        /// Called before the <see cref="PointerCaptureLost"/> event occurs.
+        /// Invoked when an unhandled <see cref="PointerCaptureLostEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
         /// </summary>
-        /// <param name="e">The event args.</param>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnPointerCaptureLost(PointerCaptureLostEventArgs e)
         {
 
         }
 
         /// <summary>
-        /// Called before the <see cref="PointerWheelChanged"/> event occurs.
+        /// Invoked when an unhandled <see cref="PointerWheelChangedEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
         /// </summary>
-        /// <param name="e">The event args.</param>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnPointerWheelChanged(PointerWheelEventArgs e)
         {
         }

src/Avalonia.Controls.ColorPicker/ColorPreviewer/ColorPreviewer.cs

@@ -96,7 +96,7 @@ namespace Avalonia.Controls.Primitives
         }
 
         /// <summary>
-        /// Called before the <see cref="ColorChanged"/> event occurs.
+        /// Raises the <see cref="ColorChanged"/> event.
         /// </summary>
         /// <param name="e">The <see cref="ColorChangedEventArgs"/> defining old/new colors.</param>
         protected virtual void OnColorChanged(ColorChangedEventArgs e)

src/Avalonia.Controls.ColorPicker/ColorSlider/ColorSlider.cs

@@ -475,7 +475,7 @@ namespace Avalonia.Controls.Primitives
         }
 
         /// <summary>
-        /// Called before the <see cref="ColorChanged"/> event occurs.
+        /// Raises the <see cref="ColorChanged"/> event.
         /// </summary>
         /// <param name="e">The <see cref="ColorChangedEventArgs"/> defining old/new colors.</param>
         protected virtual void OnColorChanged(ColorChangedEventArgs e)

src/Avalonia.Controls.ColorPicker/ColorView/ColorView.cs

@@ -286,7 +286,7 @@ namespace Avalonia.Controls
         }
 
         /// <summary>
-        /// Called before the <see cref="ColorChanged"/> event occurs.
+        /// Raises the <see cref="ColorChanged"/> event.
         /// </summary>
         /// <param name="e">The <see cref="ColorChangedEventArgs"/> defining old/new colors.</param>
         protected virtual void OnColorChanged(ColorChangedEventArgs e)

src/Avalonia.Controls/Control.cs

@@ -352,7 +352,7 @@ namespace Avalonia.Controls
         }
 
         /// <summary>
-        /// Invoked just before the <see cref="Loaded"/> event.
+        /// Raises the <see cref="Loaded"/> event.
         /// </summary>
         /// <param name="e">The event args.</param>
         protected virtual void OnLoaded(RoutedEventArgs e)
@@ -361,7 +361,7 @@ namespace Avalonia.Controls
         }
 
         /// <summary>
-        /// Invoked just before the <see cref="Unloaded"/> event.
+        /// Raises the <see cref="Unloaded"/> event.
         /// </summary>
         /// <param name="e">The event args.</param>
         protected virtual void OnUnloaded(RoutedEventArgs e)
@@ -370,7 +370,7 @@ namespace Avalonia.Controls
         }
 
         /// <summary>
-        /// Invoked just before the <see cref="SizeChanged"/> event.
+        /// Raises the <see cref="SizeChanged"/> event.
         /// </summary>
         /// <param name="e">The event args.</param>
         protected virtual void OnSizeChanged(SizeChangedEventArgs e)

src/Avalonia.Controls/Expander.cs

@@ -181,7 +181,7 @@ namespace Avalonia.Controls
         }
 
         /// <summary>
-        /// Invoked just before the <see cref="Collapsed"/> event.
+        /// Raises the <see cref="Collapsed"/> event.
         /// </summary>
         protected virtual void OnCollapsed(RoutedEventArgs eventArgs)
         {
@@ -189,7 +189,7 @@ namespace Avalonia.Controls
         }
 
         /// <summary>
-        /// Invoked just before the <see cref="Collapsing"/> event.
+        /// Raises the <see cref="Collapsing"/> event.
         /// </summary>
         protected virtual void OnCollapsing(CancelRoutedEventArgs eventArgs)
         {
@@ -197,7 +197,7 @@ namespace Avalonia.Controls
         }
 
         /// <summary>
-        /// Invoked just before the <see cref="Expanded"/> event.
+        /// Raises the <see cref="Expanded"/> event.
         /// </summary>
         protected virtual void OnExpanded(RoutedEventArgs eventArgs)
         {
@@ -205,7 +205,7 @@ namespace Avalonia.Controls
         }
 
         /// <summary>
-        /// Invoked just before the <see cref="Expanding"/> event.
+        /// Raises the <see cref="Expanding"/> event.
         /// </summary>
         protected virtual void OnExpanding(CancelRoutedEventArgs eventArgs)
         {

src/Avalonia.Controls/MenuItem.cs

@@ -466,9 +466,11 @@ namespace Avalonia.Controls
         }
 
         /// <summary>
-        /// Called when the <see cref="MenuItem"/> is clicked.
+        /// Invoked when an unhandled <see cref="ClickEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
         /// </summary>
-        /// <param name="e">The click event args.</param>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnClick(RoutedEventArgs e)
         {
             (var command, var parameter) = (Command, CommandParameter);
@@ -507,9 +509,11 @@ namespace Avalonia.Controls
         }
 
         /// <summary>
-        /// Called when a submenu is opened on this MenuItem or a child MenuItem.
+        /// Invoked when an unhandled <see cref="SubmenuOpenedEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
         /// </summary>
-        /// <param name="e">The event args.</param>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnSubmenuOpened(RoutedEventArgs e)
         {
             var menuItem = e.Source as MenuItem;

src/Avalonia.Controls/Primitives/Thumb.cs

@@ -54,14 +54,32 @@ namespace Avalonia.Controls.Primitives
 
         protected override AutomationPeer OnCreateAutomationPeer() => new ThumbAutomationPeer(this);
 
+        /// <summary>
+        /// Invoked when an unhandled <see cref="DragStartedEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
+        /// </summary>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnDragStarted(VectorEventArgs e)
         {
         }
 
+        /// <summary>
+        /// Invoked when an unhandled <see cref="DragDeltaEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
+        /// </summary>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnDragDelta(VectorEventArgs e)
         {
         }
 
+        /// <summary>
+        /// Invoked when an unhandled <see cref="DragCompletedEvent"/> reaches an element in its 
+        /// route that is derived from this class. Implement this method to add class handling 
+        /// for this event.
+        /// </summary>
+        /// <param name="e">Data about the event.</param>
         protected virtual void OnDragCompleted(VectorEventArgs e)
         {
         }