From 24e18d023618a3736a7877d27ed9eb9127554084 Mon Sep 17 00:00:00 2001
From: Steven Kirk <grokys@gmail.com>
Date: Tue, 6 Oct 2015 20:47:25 +0200
Subject: [PATCH] Documentation.

---
 src/Perspex.Controls/Button.cs                |  3 ++
 src/Perspex.Controls/Canvas.cs                | 17 +++++--
 src/Perspex.Controls/ListBox.cs               |  4 ++
 src/Perspex.Controls/MenuItem.cs              |  4 +-
 src/Perspex.Controls/PlacementMode.cs         | 12 +++++
 src/Perspex.Controls/Platform/IPopupImpl.cs   | 17 +++++--
 .../Platform/ISystemDialogImpl.cs             | 16 +++++--
 .../Platform/ITopLevelImpl.cs                 | 46 ++++++++++++++++++-
 .../Perspex.Controls.UnitTests.csproj         |  1 +
 9 files changed, 106 insertions(+), 14 deletions(-)

diff --git a/src/Perspex.Controls/Button.cs b/src/Perspex.Controls/Button.cs
index 41736206c9..29eb4c3628 100644
--- a/src/Perspex.Controls/Button.cs
+++ b/src/Perspex.Controls/Button.cs
@@ -44,6 +44,9 @@ namespace Perspex.Controls
         public static readonly PerspexProperty<ICommand> CommandProperty =
             PerspexProperty.Register<Button, ICommand>(nameof(Command));
 
+        /// <summary>
+        /// Defines the <see cref="HotKey"/> property.
+        /// </summary>
         public static readonly PerspexProperty<KeyGesture> HotKeyProperty =
             HotKeyManager.HotKeyProperty.AddOwner<Button>();
 
diff --git a/src/Perspex.Controls/Canvas.cs b/src/Perspex.Controls/Canvas.cs
index 950c7b3841..3e4612e663 100644
--- a/src/Perspex.Controls/Canvas.cs
+++ b/src/Perspex.Controls/Canvas.cs
@@ -6,28 +6,37 @@ using Perspex.Input;
 
 namespace Perspex.Controls
 {
+    /// <summary>
+    /// A panel that displays child controls at arbitrary locations.
+    /// </summary>
+    /// <remarks>
+    /// Unlike other <see cref="Panel"/> implementations, the <see cref="Canvas"/> doesn't lay out
+    /// its children in any particular layout. Instead, the positioning of each child control is
+    /// defined by the <code>Canvas.Left</code>, <code>Canvas.Top</code>, <code>Canvas.Right</code>
+    /// and <code>Canvas.Bottom</code> attached properties.
+    /// </remarks>
     public class Canvas : Panel, INavigableContainer
     {
         /// <summary>
-        /// Defines the <see cref="Left"/> property.
+        /// Defines the Left attached property.
         /// </summary>
         public static readonly PerspexProperty<double> LeftProperty =
             PerspexProperty.RegisterAttached<StackPanel, Control, double>("Left");
 
         /// <summary>
-        /// Defines the <see cref="Top"/> property.
+        /// Defines the Top attached property.
         /// </summary>
         public static readonly PerspexProperty<double> TopProperty =
             PerspexProperty.RegisterAttached<StackPanel, Control, double>("Top");
 
         /// <summary>
-        /// Defines the <see cref="Right"/> property.
+        /// Defines the Right attached property.
         /// </summary>
         public static readonly PerspexProperty<double> RightProperty =
             PerspexProperty.RegisterAttached<StackPanel, Control, double>("Right");
 
         /// <summary>
-        /// Defines the <see cref="Bottom"/> property.
+        /// Defines the Bottom attached property.
         /// </summary>
         public static readonly PerspexProperty<double> BottomProperty =
             PerspexProperty.RegisterAttached<StackPanel, Control, double>("Bottom");
diff --git a/src/Perspex.Controls/ListBox.cs b/src/Perspex.Controls/ListBox.cs
index 50eee6a7db..6b839656e7 100644
--- a/src/Perspex.Controls/ListBox.cs
+++ b/src/Perspex.Controls/ListBox.cs
@@ -6,8 +6,12 @@ using Perspex.Controls.Primitives;
 
 namespace Perspex.Controls
 {
+    /// <summary>
+    /// An <see cref="ItemsControl"/> in which individual items can be selected.
+    /// </summary>
     public class ListBox : SelectingItemsControl
     {
+        /// <inheritdoc/>
         protected override IItemContainerGenerator CreateItemContainerGenerator()
         {
             return new ItemContainerGenerator<ListBoxItem>(this);
diff --git a/src/Perspex.Controls/MenuItem.cs b/src/Perspex.Controls/MenuItem.cs
index 5a7eef3b28..24f4aa3a4b 100644
--- a/src/Perspex.Controls/MenuItem.cs
+++ b/src/Perspex.Controls/MenuItem.cs
@@ -28,6 +28,9 @@ namespace Perspex.Controls
         public static readonly PerspexProperty<ICommand> CommandProperty =
             Button.CommandProperty.AddOwner<MenuItem>();
 
+        /// <summary>
+        /// Defines the <see cref="HotKey"/> property.
+        /// </summary>
         public static readonly PerspexProperty<KeyGesture> HotKeyProperty =
             HotKeyManager.HotKeyProperty.AddOwner<MenuItem>();
 
@@ -519,7 +522,6 @@ namespace Perspex.Controls
             /// Gets a service of the specified type.
             /// </summary>
             /// <param name="serviceType">The service type.</param>
-            /// <param name="contract">An optional contract.</param>
             /// <returns>A service of the requested type.</returns>
             public object GetService(Type serviceType)
             {
diff --git a/src/Perspex.Controls/PlacementMode.cs b/src/Perspex.Controls/PlacementMode.cs
index cf65f29c63..e623f31674 100644
--- a/src/Perspex.Controls/PlacementMode.cs
+++ b/src/Perspex.Controls/PlacementMode.cs
@@ -1,11 +1,23 @@
 // Copyright (c) The Perspex Project. All rights reserved.
 // Licensed under the MIT license. See licence.md file in the project root for full license information.
 
+using Perspex.Controls.Primitives;
+
 namespace Perspex.Controls
 {
+    /// <summary>
+    /// Defines the placement for a <see cref="Popup"/> control.
+    /// </summary>
     public enum PlacementMode
     {
+        /// <summary>
+        /// The popup is placed at the bottom left of its target.
+        /// </summary>
         Bottom,
+
+        /// <summary>
+        /// The popup is placed at the top right of its target.
+        /// </summary>
         Right,
     }
 }
diff --git a/src/Perspex.Controls/Platform/IPopupImpl.cs b/src/Perspex.Controls/Platform/IPopupImpl.cs
index 087177ea0c..fc7aeb6e2a 100644
--- a/src/Perspex.Controls/Platform/IPopupImpl.cs
+++ b/src/Perspex.Controls/Platform/IPopupImpl.cs
@@ -1,18 +1,27 @@
 // Copyright (c) The Perspex Project. All rights reserved.
 // Licensed under the MIT license. See licence.md file in the project root for full license information.
 
-using System;
-using Perspex.Controls;
-using Perspex.Input.Raw;
-
 namespace Perspex.Platform
 {
+    /// <summary>
+    /// Defines a platform-specific popup window implementation.
+    /// </summary>
     public interface IPopupImpl : ITopLevelImpl
     {
+        /// <summary>
+        /// Sets the position of the popup.
+        /// </summary>
+        /// <param name="p">The position, in screen coordinates.</param>
         void SetPosition(Point p);
 
+        /// <summary>
+        /// Shows the popup.
+        /// </summary>
         void Show();
 
+        /// <summary>
+        /// Hides the popup.
+        /// </summary>
         void Hide();
     }
 }
diff --git a/src/Perspex.Controls/Platform/ISystemDialogImpl.cs b/src/Perspex.Controls/Platform/ISystemDialogImpl.cs
index 4e8f51427e..d3af982f95 100644
--- a/src/Perspex.Controls/Platform/ISystemDialogImpl.cs
+++ b/src/Perspex.Controls/Platform/ISystemDialogImpl.cs
@@ -1,14 +1,22 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
+// Copyright (c) The Perspex Project. All rights reserved.
+// Licensed under the MIT license. See licence.md file in the project root for full license information.
+
 using System.Threading.Tasks;
 using Perspex.Platform;
 
 namespace Perspex.Controls.Platform
 {
+    /// <summary>
+    /// Defines a platform-specific system dialog implementation.
+    /// </summary>
     public interface ISystemDialogImpl
     {
+        /// <summary>
+        /// Shows a file dialog.
+        /// </summary>
+        /// <param name="dialog">The details of the file dialog to show.</param>
+        /// <param name="parent">The parent window.</param>
+        /// <returns>A task returning the selected filenames.</returns>
         Task<string[]> ShowFileDialogAsync(FileDialog dialog, IWindowImpl parent);
     }
 }
diff --git a/src/Perspex.Controls/Platform/ITopLevelImpl.cs b/src/Perspex.Controls/Platform/ITopLevelImpl.cs
index 053c340b27..5b0d738e29 100644
--- a/src/Perspex.Controls/Platform/ITopLevelImpl.cs
+++ b/src/Perspex.Controls/Platform/ITopLevelImpl.cs
@@ -2,36 +2,80 @@
 // Licensed under the MIT license. See licence.md file in the project root for full license information.
 
 using System;
-using Perspex.Controls;
 using Perspex.Input;
 using Perspex.Input.Raw;
 
 namespace Perspex.Platform
 {
+    /// <summary>
+    /// Defines a platform-specific top-level window implementation.
+    /// </summary>
+    /// <remarks>
+    /// This interface is the common interface to <see cref="IWindowImpl"/> and
+    /// <see cref="IPopupImpl"/>.
+    /// </remarks>
     public interface ITopLevelImpl : IDisposable
     {
+        /// <summary>
+        /// Gets or sets the client size of the window.
+        /// </summary>
         Size ClientSize { get; set; }
 
+        /// <summary>
+        /// Gets the platform window handle.
+        /// </summary>
         IPlatformHandle Handle { get; }
 
+        /// <summary>
+        /// Gets or sets a method called when the window is activated (receives focus).
+        /// </summary>
         Action Activated { get; set; }
 
+        /// <summary>
+        /// Gets or sets a method called when the window is closed.
+        /// </summary>
         Action Closed { get; set; }
 
+        /// <summary>
+        /// Gets or sets a method called when the window is deactivated (loses focus).
+        /// </summary>
         Action Deactivated { get; set; }
 
+        /// <summary>
+        /// Gets or sets a method called when the window receives input.
+        /// </summary>
         Action<RawInputEventArgs> Input { get; set; }
 
+        /// <summary>
+        /// Gets or sets a method called when the window requires painting.
+        /// </summary>
         Action<Rect> Paint { get; set; }
 
+        /// <summary>
+        /// Gets or sets a method called when the window is resized.
+        /// </summary>
         Action<Size> Resized { get; set; }
 
+        /// <summary>
+        /// Activates the window.
+        /// </summary>
         void Activate();
 
+        /// <summary>
+        /// Invalidates a rect on the window.
+        /// </summary>
         void Invalidate(Rect rect);
 
+        /// <summary>
+        /// Sets the <see cref="IInputRoot"/> for the window.
+        /// </summary>
         void SetInputRoot(IInputRoot inputRoot);
 
+        /// <summary>
+        /// Converts a point from client to screen coordinates.
+        /// </summary>
+        /// <param name="point">The point in client coordinates.</param>
+        /// <returns>The point in screen coordinates.</returns>
         Point PointToScreen(Point point);
 
         /// <summary>
diff --git a/tests/Perspex.Controls.UnitTests/Perspex.Controls.UnitTests.csproj b/tests/Perspex.Controls.UnitTests/Perspex.Controls.UnitTests.csproj
index 29cd92b135..43854919c4 100644
--- a/tests/Perspex.Controls.UnitTests/Perspex.Controls.UnitTests.csproj
+++ b/tests/Perspex.Controls.UnitTests/Perspex.Controls.UnitTests.csproj
@@ -84,6 +84,7 @@
     <Compile Include="GridLengthTests.cs" />
     <Compile Include="ContentPresenterTests.cs" />
     <Compile Include="BorderTests.cs" />
+    <Compile Include="TreeViewTests.cs" />
     <Compile Include="Mixins\SelectableMixinTests.cs" />
     <Compile Include="StackPanelTests.cs" />
     <Compile Include="Primitives\TrackTests.cs" />