From 4996c0b1730f17f1a5dc2aeecaa5de56b0b603d3 Mon Sep 17 00:00:00 2001
From: Dan Walmsley <dan@walms.co.uk>
Date: Fri, 10 May 2019 19:30:14 +0100
Subject: [PATCH] add xml comments.

---
 .../IManagedNotificationManager.cs            | 18 +++++
 .../Notifications/INotification.cs            | 44 ++++++++++++
 .../Notifications/INotificationManager.cs     | 30 +++-----
 .../Notifications/Notification.cs             | 24 ++++++-
 .../Notifications/NotificationCard.cs         | 72 +++++++++----------
 .../Notifications/NotificationPosition.cs     | 16 +++++
 .../Notifications/NotificationType.cs         |  8 ++-
 .../Notifications/ReversibleStackPanel.cs     | 13 ++--
 .../WindowNotificationManager.cs              | 40 ++++++++---
 9 files changed, 191 insertions(+), 74 deletions(-)
 create mode 100644 src/Avalonia.Controls/Notifications/IManagedNotificationManager.cs
 create mode 100644 src/Avalonia.Controls/Notifications/INotification.cs
 create mode 100644 src/Avalonia.Controls/Notifications/NotificationPosition.cs

diff --git a/src/Avalonia.Controls/Notifications/IManagedNotificationManager.cs b/src/Avalonia.Controls/Notifications/IManagedNotificationManager.cs
new file mode 100644
index 0000000000..330013317f
--- /dev/null
+++ b/src/Avalonia.Controls/Notifications/IManagedNotificationManager.cs
@@ -0,0 +1,18 @@
+// Copyright (c) The Avalonia Project. All rights reserved.
+// Licensed under the MIT license. See licence.md file in the project root for full license information.
+
+namespace Avalonia.Controls.Notifications
+{
+    /// <summary>
+    /// Interface for a managed notification manager.
+    /// Managed notification managers can show any content.
+    /// </summary>
+    public interface IManagedNotificationManager : INotificationManager
+    {
+        /// <summary>
+        /// Shows a notification.
+        /// </summary>
+        /// <param name="content">The content to be displayed.</param>
+        void Show(object content);
+    }
+}
diff --git a/src/Avalonia.Controls/Notifications/INotification.cs b/src/Avalonia.Controls/Notifications/INotification.cs
new file mode 100644
index 0000000000..7ad2c770a6
--- /dev/null
+++ b/src/Avalonia.Controls/Notifications/INotification.cs
@@ -0,0 +1,44 @@
+// Copyright (c) The Avalonia Project. All rights reserved.
+// Licensed under the MIT license. See licence.md file in the project root for full license information.
+
+using System;
+
+namespace Avalonia.Controls.Notifications
+{
+    /// <summary>
+    /// Interface for a notification.
+    /// </summary>
+    public interface INotification
+    {
+        /// <summary>
+        /// Gets the Title of the notification.
+        /// </summary>
+        string Title { get; }
+
+        /// <summary>
+        /// Gets the Message of the notification.
+        /// </summary>
+        string Message { get; }
+
+        /// <summary>
+        /// Gets the <see cref="NotificationType"/> of the notification.
+        /// </summary>
+        NotificationType Type { get; }
+
+        /// <summary>
+        /// Gets the expiration time of the notification after which it will automatically close.
+        /// If the value is <see cref="TimeSpan.Zero"/> then the notification will remain open until the user closes it.
+        /// </summary>
+        TimeSpan Expiration { get; }
+
+        /// <summary>
+        /// Gets an Action to be run when the notification is clicked.
+        /// </summary>
+        Action OnClick { get; }
+
+        /// <summary>
+        /// Gets an Action to be run when the notification is closed.
+        /// </summary>
+        Action OnClose { get; }
+    }
+}
diff --git a/src/Avalonia.Controls/Notifications/INotificationManager.cs b/src/Avalonia.Controls/Notifications/INotificationManager.cs
index f2af87fb4a..53c3d68f8e 100644
--- a/src/Avalonia.Controls/Notifications/INotificationManager.cs
+++ b/src/Avalonia.Controls/Notifications/INotificationManager.cs
@@ -1,29 +1,17 @@
-using System;
+// Copyright (c) The Avalonia Project. All rights reserved.
+// Licensed under the MIT license. See licence.md file in the project root for full license information.
 
 namespace Avalonia.Controls.Notifications
 {
-    public interface INotification
-    {
-        string Title { get; }
-
-        string Message { get; }
-
-        NotificationType Type { get; }
-
-        TimeSpan Expiration { get; }
-
-        Action OnClick { get; }
-
-        Action OnClose { get; }
-    }
-
+    /// <summary>
+    /// Defines the interfaces for NotificationManagers.
+    /// </summary>
     public interface INotificationManager
     {
+        /// <summary>
+        /// Show a notification.
+        /// </summary>
+        /// <param name="notification">The notification to be displayed.</param>
         void Show(INotification notification);
     }
-
-    public interface IManagedNotificationManager : INotificationManager
-    {
-        void Show(object content);
-    }
 }
diff --git a/src/Avalonia.Controls/Notifications/Notification.cs b/src/Avalonia.Controls/Notifications/Notification.cs
index 4aea4e5f9d..b488d3a487 100644
--- a/src/Avalonia.Controls/Notifications/Notification.cs
+++ b/src/Avalonia.Controls/Notifications/Notification.cs
@@ -1,15 +1,29 @@
-using System;
+// Copyright (c) The Avalonia Project. All rights reserved.
+// Licensed under the MIT license. See licence.md file in the project root for full license information.
+
+using System;
 
 namespace Avalonia.Controls.Notifications
 {
     /// <summary>
-    /// Defines content for a <see cref="NotificationCard"/> control.
+    /// Implements the INotification interfaces.
+    /// Can be displayed by both <see cref="INotificationManager"/> and <see cref="IManagedNotificationManager"/>
     /// </summary>
     /// <remarks>
     /// This notification content type is compatible with native notifications.
     /// </remarks>
     public class Notification : INotification
     {
+        /// <summary>
+        /// Instantiates an instance of <see cref="Notification"/>
+        /// </summary>
+        /// <param name="title">The title of the notification.</param>
+        /// <param name="message">The message to be displayed in the notification.</param>
+        /// <param name="type">The <see cref="NotificationType"/> of the notification.</param>
+        /// <param name="expiration">The expiry time at which the notification will close. 
+        /// Use <see cref="TimeSpan.Zero"/> for notifications that will remain open.</param>
+        /// <param name="onClick">The Action to call when the notification is clicked.</param>
+        /// <param name="onClose">The Action to call when the notification is closed.</param>
         public Notification(string title,
             string message,
             NotificationType type = NotificationType.Information,
@@ -25,16 +39,22 @@ namespace Avalonia.Controls.Notifications
             OnClose = onClose;
         }
 
+        /// <inheritdoc/>
         public string Title { get; private set; }
 
+        /// <inheritdoc/>
         public string Message { get; private set; }
 
+        /// <inheritdoc/>
         public NotificationType Type { get; private set; }
 
+        /// <inheritdoc/>
         public TimeSpan Expiration { get; private set; }
 
+        /// <inheritdoc/>
         public Action OnClick { get; private set; }
 
+        /// <inheritdoc/>
         public Action OnClose { get; private set; }
     }
 }
diff --git a/src/Avalonia.Controls/Notifications/NotificationCard.cs b/src/Avalonia.Controls/Notifications/NotificationCard.cs
index feb9479a19..6b326073a6 100644
--- a/src/Avalonia.Controls/Notifications/NotificationCard.cs
+++ b/src/Avalonia.Controls/Notifications/NotificationCard.cs
@@ -1,24 +1,38 @@
-using System;
+// Copyright (c) The Avalonia Project. All rights reserved.
+// Licensed under the MIT license. See licence.md file in the project root for full license information.
+
+using System;
 using System.Linq;
 using System.Reactive.Linq;
-using Avalonia.Controls.Primitives;
 using Avalonia.Interactivity;
 using Avalonia.LogicalTree;
 
 namespace Avalonia.Controls.Notifications
 {
+    /// <summary>
+    /// Control that represents and displays a notification.
+    /// </summary>
     public class NotificationCard : ContentControl
     {
         private bool _isClosed;
         private bool _isClosing;
 
-        static NotificationCard()
-        {
-            IsClosedProperty.Changed.AddClassHandler<NotificationCard>(IsClosedChanged);
-        }
-
+        /// <summary>
+        /// Instantiates a new instance of <see cref="NotificationCard"/>.
+        /// </summary>
         public NotificationCard()
         {
+            this.GetObservable(IsClosedProperty)
+                .Subscribe(x =>
+                {
+                    if (!IsClosing & !IsClosed)
+                    {
+                        return;
+                    }
+
+                    RaiseEvent(new RoutedEventArgs(NotificationClosedEvent));
+                });
+
             this.GetObservable(ContentProperty)
                 .OfType<Notification>()
                 .Subscribe(x =>
@@ -53,6 +67,9 @@ namespace Avalonia.Controls.Notifications
             private set { SetAndRaise(IsClosingProperty, ref _isClosing, value); }
         }
 
+        /// <summary>
+        /// Defines the <see cref="IsClosing"/> property.
+        /// </summary>
         public static readonly DirectProperty<NotificationCard, bool> IsClosingProperty =
             AvaloniaProperty.RegisterDirect<NotificationCard, bool>(nameof(IsClosing), o => o.IsClosing);
 
@@ -92,6 +109,9 @@ namespace Avalonia.Controls.Notifications
             remove { RemoveHandler(NotificationCloseInvokedEvent, value); }
         }
 
+        /// <summary>
+        /// Raised when the <see cref="NotificationCard"/> has closed.
+        /// </summary>
         public event EventHandler<RoutedEventArgs> NotificationClosed
         {
             add { AddHandler(NotificationClosedEvent, value); }
@@ -108,6 +128,9 @@ namespace Avalonia.Controls.Notifications
             obj.SetValue(CloseOnClickProperty, value);
         }
 
+        /// <summary>
+        /// Defines the CloseOnClick property.
+        /// </summary>
         public static readonly AvaloniaProperty CloseOnClickProperty =
           AvaloniaProperty.RegisterAttached<Button, bool>("CloseOnClick", typeof(NotificationCard), validate: CloseOnClickChanged);
 
@@ -125,6 +148,9 @@ namespace Avalonia.Controls.Notifications
             return true;
         }
 
+        /// <summary>
+        /// Called when a button inside the Notification is clicked.
+        /// </summary>
         private static void Button_Click(object sender, RoutedEventArgs e)
         {
             var btn = sender as ILogical;
@@ -132,25 +158,9 @@ namespace Avalonia.Controls.Notifications
             notification?.Close();
         }
 
-        protected override void OnTemplateApplied(TemplateAppliedEventArgs e)
-        {
-            base.OnTemplateApplied(e);
-            var closeButton = this.FindControl<Button>("PART_CloseButton");
-            if (closeButton != null)
-                closeButton.Click += OnCloseButtonOnClick;
-
-        }
-
-        private void OnCloseButtonOnClick(object sender, RoutedEventArgs args)
-        {
-            var button = sender as Button;
-            if (button == null)
-                return;
-
-            button.Click -= OnCloseButtonOnClick;
-            Close();
-        }
-
+        /// <summary>
+        /// Closes the <see cref="NotificationCard"/>.
+        /// </summary>
         public void Close()
         {
             if (IsClosing)
@@ -162,15 +172,5 @@ namespace Avalonia.Controls.Notifications
 
             RaiseEvent(new RoutedEventArgs(NotificationCloseInvokedEvent));
         }
-
-        private static void IsClosedChanged(NotificationCard target, AvaloniaPropertyChangedEventArgs arg2)
-        {
-            if (!target.IsClosing & !target.IsClosed)
-            {
-                return;
-            }
-
-            target.RaiseEvent(new RoutedEventArgs(NotificationClosedEvent));
-        }
     }
 }
diff --git a/src/Avalonia.Controls/Notifications/NotificationPosition.cs b/src/Avalonia.Controls/Notifications/NotificationPosition.cs
new file mode 100644
index 0000000000..ce55aafdb9
--- /dev/null
+++ b/src/Avalonia.Controls/Notifications/NotificationPosition.cs
@@ -0,0 +1,16 @@
+// Copyright (c) The Avalonia Project. All rights reserved.
+// Licensed under the MIT license. See licence.md file in the project root for full license information.
+
+namespace Avalonia.Controls.Notifications
+{
+    /// <summary>
+    /// Enumeration of Notifications positions.
+    /// </summary>
+    public enum NotificationPosition
+    {
+        TopLeft,
+        TopRight,
+        BottomLeft,
+        BottomRight
+    }
+}
diff --git a/src/Avalonia.Controls/Notifications/NotificationType.cs b/src/Avalonia.Controls/Notifications/NotificationType.cs
index cbacc85aef..fdcf5eec0a 100644
--- a/src/Avalonia.Controls/Notifications/NotificationType.cs
+++ b/src/Avalonia.Controls/Notifications/NotificationType.cs
@@ -1,5 +1,11 @@
-namespace Avalonia.Controls.Notifications
+// Copyright (c) The Avalonia Project. All rights reserved.
+// Licensed under the MIT license. See licence.md file in the project root for full license information.
+
+namespace Avalonia.Controls.Notifications
 {
+    /// <summary>
+    /// Enumeration of types for <see cref="INotification"/>.
+    /// </summary>
     public enum NotificationType
     {
         Information,
diff --git a/src/Avalonia.Controls/Notifications/ReversibleStackPanel.cs b/src/Avalonia.Controls/Notifications/ReversibleStackPanel.cs
index b635c790e1..768d87c63e 100644
--- a/src/Avalonia.Controls/Notifications/ReversibleStackPanel.cs
+++ b/src/Avalonia.Controls/Notifications/ReversibleStackPanel.cs
@@ -1,19 +1,22 @@
-using System;
-using System.Collections.Generic;
+// Copyright (c) The Avalonia Project. All rights reserved.
+// Licensed under the MIT license. See licence.md file in the project root for full license information.
+
+using System;
 using System.Linq;
-using System.Text;
 using Avalonia.Layout;
-using Avalonia.Styling;
 
 namespace Avalonia.Controls
 {
+    /// <summary>
+    /// Implements a <see cref="StackPanel"/> where the flow direction of its items can be reversed.
+    /// </summary>
     public class ReversibleStackPanel : StackPanel
     {
         /// <summary>
         /// Defines the <see cref="ReverseOrder"/> property.
         /// </summary>
         public static readonly StyledProperty<bool> ReverseOrderProperty =
-            AvaloniaProperty.Register<ReversibleStackPanel, bool>(nameof(ReverseOrder));        
+            AvaloniaProperty.Register<ReversibleStackPanel, bool>(nameof(ReverseOrder));
 
         /// <summary>
         /// Gets or sets if the child controls will be layed out in reverse order.
diff --git a/src/Avalonia.Controls/Notifications/WindowNotificationManager.cs b/src/Avalonia.Controls/Notifications/WindowNotificationManager.cs
index b17b253569..3dffea160d 100644
--- a/src/Avalonia.Controls/Notifications/WindowNotificationManager.cs
+++ b/src/Avalonia.Controls/Notifications/WindowNotificationManager.cs
@@ -1,3 +1,6 @@
+// Copyright (c) The Avalonia Project. All rights reserved.
+// Licensed under the MIT license. See licence.md file in the project root for full license information.
+
 using System;
 using System.Collections;
 using System.Linq;
@@ -8,28 +11,47 @@ using Avalonia.VisualTree;
 
 namespace Avalonia.Controls.Notifications
 {
+    /// <summary>
+    /// Defines a WindowNotificationManager control.
+    /// </summary>
     public class WindowNotificationManager : TemplatedControl, IManagedNotificationManager
     {
         private IList _items;
 
+        /// <summary>
+        /// Defines the <see cref="Position"/> property.
+        /// </summary>
         public static readonly StyledProperty<NotificationPosition> PositionProperty =
           AvaloniaProperty.Register<WindowNotificationManager, NotificationPosition>(nameof(Position), NotificationPosition.TopRight);
 
+        /// <summary>
+        /// Defines which corner of the screen notifications can be displayed in. <seealso cref="NotificationPosition"/>.
+        /// </summary>
         public NotificationPosition Position
         {
             get { return GetValue(PositionProperty); }
             set { SetValue(PositionProperty, value); }
         }
 
+        /// <summary>
+        /// Defines the <see cref="MaxItems"/> property.
+        /// </summary>
         public static readonly StyledProperty<int> MaxItemsProperty =
           AvaloniaProperty.Register<WindowNotificationManager, int>(nameof(MaxItems), 5);
 
+        /// <summary>
+        /// Defines the maximum number of notifications visible at once.
+        /// </summary>
         public int MaxItems
         {
             get { return GetValue(MaxItemsProperty); }
             set { SetValue(MaxItemsProperty, value); }
         }
 
+        /// <summary>
+        /// Instantiates a new instance of <see cref="WindowNotificationManager"/>.
+        /// </summary>
+        /// <param name="host">The window that will host the control.</param>
         public WindowNotificationManager(Window host)
         {
             if (VisualChildren.Count != 0)
@@ -57,6 +79,7 @@ namespace Avalonia.Controls.Notifications
             VerticalAlignmentProperty.OverrideDefaultValue<WindowNotificationManager>(Layout.VerticalAlignment.Stretch);
         }
 
+        /// <inheritdoc/>
         protected override void OnTemplateApplied(TemplateAppliedEventArgs e)
         {
             base.OnTemplateApplied(e);
@@ -65,11 +88,13 @@ namespace Avalonia.Controls.Notifications
             _items = itemsControl?.Children;
         }
 
+        /// <inheritdoc/>
         public void Show(INotification content)
         {
             Show(content as object);
         }
 
+        /// <inheritdoc/>
         public async void Show(object content)
         {
             var notification = content as INotification;
@@ -106,7 +131,7 @@ namespace Avalonia.Controls.Notifications
                 _items.OfType<NotificationCard>().First(i => !i.IsClosing).Close();
             }
 
-            if (notification != null && notification.Expiration == TimeSpan.MaxValue)
+            if (notification != null && notification.Expiration == TimeSpan.Zero)
             {
                 return;
             }
@@ -116,6 +141,11 @@ namespace Avalonia.Controls.Notifications
             notificationControl.Close();
         }
 
+        /// <summary>
+        /// Installs the <see cref="WindowNotificationManager"/> within the <see cref="AdornerLayer"/>
+        /// of the host <see cref="Window"/>.
+        /// </summary>
+        /// <param name="host">The <see cref="Window"/> that will be the host.</param>
         private void Install(Window host)
         {
             var adornerLayer = host.GetVisualDescendants()
@@ -129,12 +159,4 @@ namespace Avalonia.Controls.Notifications
             }
         }
     }
-
-    public enum NotificationPosition
-    {
-        TopLeft,
-        TopRight,
-        BottomLeft,
-        BottomRight
-    }
 }