Add more XML documentation.

Author: jpobst

src/Modern.Forms/Cursor.cs

@@ -5,6 +5,9 @@
 
 namespace Modern.Forms
 {
+    /// <summary>
+    /// Represents a mouse cursor.
+    /// </summary>
     public class Cursor
     {
         internal Avalonia.Input.Cursor cursor;
@@ -14,6 +17,9 @@ internal Cursor (StandardCursorType type)
             cursor = new Avalonia.Input.Cursor (type);
         }
 
+        /// <summary>
+        /// The default cursor provided by the operating system.
+        /// </summary>
         public static Cursor Default => Cursors.Arrow;
     }
 }

src/Modern.Forms/Cursors.cs

@@ -4,6 +4,9 @@
 
 namespace Modern.Forms
 {
+    /// <summary>
+    /// Represents a collection of system provided mouse cursors.
+    /// </summary>
     public static class Cursors
     {
         private static Cursor? app_starting;
@@ -30,28 +33,119 @@ public static class Cursors
         private static Cursor? up_arrow;
         private static Cursor? wait;
 
+        /// <summary>
+        /// The default app starting cursor provided by the operating system.
+        /// </summary>
         public static Cursor AppStarting => app_starting ??= new Cursor (Avalonia.Input.StandardCursorType.AppStarting);
+
+        /// <summary>
+        /// The default arrow cursor provided by the operating system.
+        /// </summary>
         public static Cursor Arrow => arrow ??= new Cursor (Avalonia.Input.StandardCursorType.Arrow);
+
+        /// <summary>
+        /// The default bottom left corner cursor provided by the operating system.
+        /// </summary>
         public static Cursor BottomLeftCorner => bottom_left_corner ??= new Cursor (Avalonia.Input.StandardCursorType.BottomLeftCorner);
+
+        /// <summary>
+        /// The default bottom right corner cursor provided by the operating system.
+        /// </summary>
         public static Cursor BottomRightCorner => bottom_right_corner ??= new Cursor (Avalonia.Input.StandardCursorType.BottomRightCorner);
+
+        /// <summary>
+        /// The default bottom cursor provided by the operating system.
+        /// </summary>
         public static Cursor BottomSide => bottom_side ??= new Cursor (Avalonia.Input.StandardCursorType.BottomSide);
+
+        /// <summary>
+        /// The default cross cursor provided by the operating system.
+        /// </summary>
         public static Cursor Cross => cross ??= new Cursor (Avalonia.Input.StandardCursorType.Cross);
+
+        /// <summary>
+        /// The default drag copy cursor provided by the operating system.
+        /// </summary>
         public static Cursor DragCopy => drag_copy ??= new Cursor (Avalonia.Input.StandardCursorType.DragCopy);
+
+        /// <summary>
+        /// The default drag link cursor provided by the operating system.
+        /// </summary>
         public static Cursor DragLink => drag_link ??= new Cursor (Avalonia.Input.StandardCursorType.DragLink);
+
+        /// <summary>
+        /// The default drag move cursor provided by the operating system.
+        /// </summary>
         public static Cursor DragMove => drag_move ??= new Cursor (Avalonia.Input.StandardCursorType.DragMove);
+
+        /// <summary>
+        /// The default hand cursor provided by the operating system.
+        /// </summary>
         public static Cursor Hand => hand ??= new Cursor (Avalonia.Input.StandardCursorType.Hand);
+
+        /// <summary>
+        /// The default help cursor provided by the operating system.
+        /// </summary>
         public static Cursor Help => help ??= new Cursor (Avalonia.Input.StandardCursorType.Help);
+
+        /// <summary>
+        /// The default ibeam cursor provided by the operating system.
+        /// </summary>
         public static Cursor IBeam => ibeam ??= new Cursor (Avalonia.Input.StandardCursorType.Ibeam);
+
+        /// <summary>
+        /// The default left side cursor provided by the operating system.
+        /// </summary>
         public static Cursor LeftSide => left_side ??= new Cursor (Avalonia.Input.StandardCursorType.LeftSide);
+
+        /// <summary>
+        /// The default no cursor provided by the operating system.
+        /// </summary>
         public static Cursor No => no ??= new Cursor (Avalonia.Input.StandardCursorType.No);
+
+        /// <summary>
+        /// The default right side cursor provided by the operating system.
+        /// </summary>
         public static Cursor RightSide => right_side ??= new Cursor (Avalonia.Input.StandardCursorType.RightSide);
+
+        /// <summary>
+        /// The default size all cursor provided by the operating system.
+        /// </summary>
         public static Cursor SizeAll => size_all ??= new Cursor (Avalonia.Input.StandardCursorType.SizeAll);
+
+        /// <summary>
+        /// The default size north-south cursor provided by the operating system.
+        /// </summary>
         public static Cursor SizeNorthSouth => size_north_south ??= new Cursor (Avalonia.Input.StandardCursorType.SizeNorthSouth);
+
+        /// <summary>
+        /// The default size west-east cursor provided by the operating system.
+        /// </summary>
         public static Cursor SizeWestEast => size_west_east ??= new Cursor (Avalonia.Input.StandardCursorType.SizeWestEast);
+
+        /// <summary>
+        /// The default top left corner cursor provided by the operating system.
+        /// </summary>
         public static Cursor TopLeftCorner => top_left_corner ??= new Cursor (Avalonia.Input.StandardCursorType.TopLeftCorner);
+
+        /// <summary>
+        /// The default top right corner cursor provided by the operating system.
+        /// </summary>
         public static Cursor TopRightCorner => top_right_corner ??= new Cursor (Avalonia.Input.StandardCursorType.TopRightCorner);
+
+        /// <summary>
+        /// The default top side cursor provided by the operating system.
+        /// </summary>
         public static Cursor TopSide => top_side ??= new Cursor (Avalonia.Input.StandardCursorType.TopSide);
+
+        /// <summary>
+        /// The default up arrow cursor provided by the operating system.
+        /// </summary>
         public static Cursor UpArrow => up_arrow ??= new Cursor (Avalonia.Input.StandardCursorType.UpArrow);
+
+        /// <summary>
+        /// The default wait cursor provided by the operating system.
+        /// </summary>
         public static Cursor Wait => wait ??= new Cursor (Avalonia.Input.StandardCursorType.Wait);
     }
 }

src/Modern.Forms/FileDialog.cs

@@ -5,10 +5,18 @@
 
 namespace Modern.Forms
 {
+    /// <summary>
+    /// Represents a base class for file dialogs.
+    /// </summary>
     public abstract class FileDialog : FileSystemDialog
     {
         internal List<FileDialogFilter> filters = new List<FileDialogFilter> ();
 
+        /// <summary>
+        /// Adds a file filter choice to the dialog.
+        /// </summary>
+        /// <param name="name">Name of the filter, for example: "Text Files".</param>
+        /// <param name="extensions">File extensions to filter for, for example: "txt", "log".</param>
         public void AddFilter (string name, params string[] extensions)
         {
             var filter = new FileDialogFilter {
@@ -19,6 +27,9 @@ public void AddFilter (string name, params string[] extensions)
             filters.Add (filter);
         }
 
+        /// <summary>
+        /// Gets or sets the selected files. If there are multiple files selected, the first one is returned.
+        /// </summary>
         public string? FileName {
             get => FileNames.Count > 0 ? Path.GetFullPath (FileNames[0]) : null;
             set {
@@ -29,6 +40,9 @@ public string? FileName {
             }
         }
 
+        /// <summary>
+        /// Gets or sets the selected files.
+        /// </summary>
         public List<string> FileNames { get; } = new List<string> ();
     }
 }

src/Modern.Forms/FileSystemDialog.cs

@@ -2,10 +2,19 @@
 
 namespace Modern.Forms
 {
+    /// <summary>
+    /// Represents a base class for file system dialogs.
+    /// </summary>
     public abstract class FileSystemDialog
     {
+        /// <summary>
+        /// Gets or sets the initial directory for the dialog.
+        /// </summary>
         public string? InitialDirectory { get; set; }
 
+        /// <summary>
+        /// Gets or sets the title for the dialog.
+        /// </summary>
         public string Title { get; set; } = string.Empty;
     }
 }

src/Modern.Forms/FolderBrowserDialog.cs

@@ -3,18 +3,28 @@
 
 namespace Modern.Forms
 {
+    /// <summary>
+    /// Represents a dialog for choosing a file system directory.
+    /// </summary>
     public class FolderBrowserDialog : FileSystemDialog
     {
+        /// <summary>
+        /// Gets or sets the selected folder path.
+        /// </summary>
         public string? SelectedPath { get; set; }
 
-        public async Task<DialogResult> ShowDialog (Window window)
+        /// <summary>
+        /// Shows the dialog to the user.
+        /// </summary>
+        /// <param name="owner">The window that owns this dialog.</param>
+        public async Task<DialogResult> ShowDialog (Window owner)
         {
             var dialog = new Avalonia.Controls.OpenFolderDialog {
                 Directory = InitialDirectory,
                 Title = Title,
             };
 
-            SelectedPath = await dialog.ShowAsync (window.window);
+            SelectedPath = await dialog.ShowAsync (owner.window);
 
             return SelectedPath is null ? DialogResult.Cancel : DialogResult.OK;
         }

src/Modern.Forms/ILayoutable.cs

@@ -5,10 +5,25 @@
 
 namespace Modern.Forms
 {
+    /// <summary>
+    /// Provides functionality needed to be laid out by a LayoutEngine.
+    /// </summary>
     public interface ILayoutable
     {
+        /// <summary>
+        /// Gets the size the control would prefer to be.
+        /// </summary>
+        /// <param name="proposedSize">A size the layout engine is proposing for the control.</param>
         Size GetPreferredSize (Size proposedSize);
-        void SetBounds (int x, int y, int width, int height, BoundsSpecified specified = BoundsSpecified.All);
+
+        /// <summary>
+        /// Gets or sets how much space there should be between the control and other controls.
+        /// </summary>
         Padding Margin { get; }
+
+        /// <summary>
+        /// Sets the unscaled bounds of the control.
+        /// </summary>
+        void SetBounds (int x, int y, int width, int height, BoundsSpecified specified = BoundsSpecified.All);
     }
 }

src/Modern.Forms/KeyEventArgs.cs

@@ -1,64 +1,88 @@
-// Permission is hereby granted, free of charge, to any person obtaining
-// a copy of this software and associated documentation files (the
-// "Software"), to deal in the Software without restriction, including
-// without limitation the rights to use, copy, modify, merge, publish,
-// distribute, sublicense, and/or sell copies of the Software, and to
-// permit persons to whom the Software is furnished to do so, subject to
-// the following conditions:
-// 
-// The above copyright notice and this permission notice shall be
-// included in all copies or substantial portions of the Software.
-// 
-// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-//
-// Copyright (c) 2004-2005 Novell, Inc.
-//
-// Authors:
-//	Peter Bartok	pbartok@novell.com
-//
-//
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
 
 using System;
 using Avalonia.Input;
 
 namespace Modern.Forms
 {
+    /// <summary>
+    ///  Provides data for the KeyDown or KeyUp event.
+    /// </summary>
     public class KeyEventArgs : EventArgs
     {
-        private bool supress_key_press;
+        private bool _suppressKeyPress = false;
 
+        /// <summary>
+        ///  Initializes a new instance of the KeyEventArgs class.
+        /// </summary>
         public KeyEventArgs (Keys keyData)
         {
             KeyData = keyData;
-            Handled = false;
         }
 
-        public virtual bool Alt => KeyData.HasFlag (Keys.Alt);
+        /// <summary>
+        ///  Gets a value indicating whether the ALT key was pressed.
+        /// </summary>
+        public virtual bool Alt => (KeyData & Keys.Alt) == Keys.Alt;
 
-        public virtual bool Control => KeyData.HasFlag (Keys.Control);
+        /// <summary>
+        ///  Gets a value indicating whether the CTRL key was pressed.
+        /// </summary>
+        public bool Control => (KeyData & Keys.Control) == Keys.Control;
 
+        /// <summary>
+        ///  Gets or sets a value indicating whether the event was handled.
+        /// </summary>
         public bool Handled { get; set; }
 
-        public Keys KeyCode => KeyData & Keys.KeyCode;
+        /// <summary>
+        ///  Gets the keyboard code for a KeyDown or KeyUp event.
+        /// </summary>
+        public Keys KeyCode {
+            get {
+                var keyGenerated = KeyData & Keys.KeyCode;
 
-        public Keys KeyData { get; }
+                // since Keys can be discontiguous, keeping Enum.IsDefined.
+                if (!Enum.IsDefined (typeof (Keys), (int)keyGenerated)) {
+                    return Keys.None;
+                }
+                return keyGenerated;
+            }
+        }
 
-        public int KeyValue => Convert.ToInt32 (KeyData);
+        /// <summary>
+        ///  Gets the keyboard value for a <see cref='Forms.Control.KeyDown'/> or
+        /// <see cref='Forms.Control.KeyUp'/> event.
+        /// </summary>
+        public int KeyValue => (int)(KeyData & Keys.KeyCode);
+
+        /// <summary>
+        ///  Gets the key data for a <see cref='Forms.Control.KeyDown'/> or
+        /// <see cref='Forms.Control.KeyUp'/> event.
+        /// </summary>
+        public Keys KeyData { get; }
 
+        /// <summary>
+        ///  Gets the modifier flags for a <see cref='Forms.Control.KeyDown'/> or
+        /// <see cref='Forms.Control.KeyUp'/> event.
+        ///  This indicates which modifier keys (CTRL, SHIFT, and/or ALT) were pressed.
+        /// </summary>
         public Keys Modifiers => KeyData & Keys.Modifiers;
 
-        public virtual bool Shift => KeyData.HasFlag (Keys.Shift);
+        /// <summary>
+        ///  Gets a value indicating whether the SHIFT key was pressed.
+        /// </summary>
+        public virtual bool Shift => (KeyData & Keys.Shift) == Keys.Shift;
 
+        /// <summary>
+        /// Gets or sets a value indicating the key press should be suppressed.
+        /// </summary>
         public bool SuppressKeyPress {
-            get => supress_key_press;
+            get => _suppressKeyPress;
             set {
-                supress_key_press = value;
+                _suppressKeyPress = value;
                 Handled = value;
             }
         }