From 4e443c87bd84241dd9e7905e1daa3a3b8bcb6c07 Mon Sep 17 00:00:00 2001
From: Steven Kirk <grokys@gmail.com>
Date: Fri, 24 Jul 2015 19:28:17 +0200
Subject: [PATCH] More porting docs etc from ideas branch.

---
 Perspex.Controls/DefinitionBase.cs            | 15 ++++--
 Perspex.Controls/ISelectable.cs               | 18 ++++++-
 Perspex.Controls/Image.cs                     | 52 ++++++++++++++-----
 Perspex.Controls/Primitives/AccessText.cs     |  4 +-
 .../Primitives/HeaderedContentControl.cs      | 11 +++-
 .../Primitives/SelectingItemsControl.cs       |  4 +-
 Perspex.Controls/TextBlock.cs                 | 42 +++++++++++----
 Perspex.Controls/TextWrapping.cs              | 14 ++++-
 8 files changed, 123 insertions(+), 37 deletions(-)

diff --git a/Perspex.Controls/DefinitionBase.cs b/Perspex.Controls/DefinitionBase.cs
index f36cab0052..aca0b55859 100644
--- a/Perspex.Controls/DefinitionBase.cs
+++ b/Perspex.Controls/DefinitionBase.cs
@@ -1,20 +1,29 @@
 // -----------------------------------------------------------------------
 // <copyright file="DefinitionBase.cs" company="Steven Kirk">
-// Copyright 2013 MIT Licence. See licence.md for more information.
+// Copyright 2015 MIT Licence. See licence.md for more information.
 // </copyright>
 // -----------------------------------------------------------------------
 
 namespace Perspex.Controls
 {
+    /// <summary>
+    /// Base class for <see cref="ColumnDefinition"/> and <see cref="RowDefinition"/>.
+    /// </summary>
     public class DefinitionBase : PerspexObject
     {
+        /// <summary>
+        /// Defines the <see cref="SharedSizeGroup"/> property.
+        /// </summary>
         public static readonly PerspexProperty<string> SharedSizeGroupProperty =
-            PerspexProperty.Register<DefinitionBase, string>("SharedSizeGroup", inherits: true);
+            PerspexProperty.Register<DefinitionBase, string>(nameof(SharedSizeGroup), inherits: true);
 
+        /// <summary>
+        /// Gets or sets the name of the shared size group of the column or row.
+        /// </summary>
         public string SharedSizeGroup
         {
             get { return this.GetValue(SharedSizeGroupProperty); }
             set { this.SetValue(SharedSizeGroupProperty, value); }
         }
     }
-}
+}
\ No newline at end of file
diff --git a/Perspex.Controls/ISelectable.cs b/Perspex.Controls/ISelectable.cs
index dae37394fa..405e1161b1 100644
--- a/Perspex.Controls/ISelectable.cs
+++ b/Perspex.Controls/ISelectable.cs
@@ -1,13 +1,27 @@
 // -----------------------------------------------------------------------
 // <copyright file="ISelectable.cs" company="Steven Kirk">
-// Copyright 2014 MIT Licence. See licence.md for more information.
+// Copyright 2015 MIT Licence. See licence.md for more information.
 // </copyright>
 // -----------------------------------------------------------------------
 
 namespace Perspex.Controls
 {
+    using Perspex.Controls.Primitives;
+
+    /// <summary>
+    /// Interface for objects that are selectable.
+    /// </summary>
+    /// <remarks>
+    /// Controls such as <see cref="Selector"/> use this interface to indicate the selected
+    /// control in a list. If changing the control's <see cref="IsSelected"/> property should
+    /// update the selection in a <see cref="SelectingItemsControl"/> or equivalent, then the
+    /// control should raise the <see cref="SelectingItemsControl.IsSelectedChangedEvent"/>.
+    /// </remarks>
     public interface ISelectable
     {
+        /// <summary>
+        /// Gets or sets the selected state of the object.
+        /// </summary>
         bool IsSelected { get; set; }
     }
-}
+}
\ No newline at end of file
diff --git a/Perspex.Controls/Image.cs b/Perspex.Controls/Image.cs
index 3e3ef957b2..698d4dc206 100644
--- a/Perspex.Controls/Image.cs
+++ b/Perspex.Controls/Image.cs
@@ -1,6 +1,6 @@
 // -----------------------------------------------------------------------
 // <copyright file="Image.cs" company="Steven Kirk">
-// Copyright 2013 MIT Licence. See licence.md for more information.
+// Copyright 2015 MIT Licence. See licence.md for more information.
 // </copyright>
 // -----------------------------------------------------------------------
 
@@ -10,27 +10,46 @@ namespace Perspex.Controls
     using Perspex.Media;
     using Perspex.Media.Imaging;
 
+    /// <summary>
+    /// Displays a <see cref="Bitmap"/> image.
+    /// </summary>
     public class Image : Control
     {
+        /// <summary>
+        /// Defines the <see cref="Source"/> property.
+        /// </summary>
         public static readonly PerspexProperty<Bitmap> SourceProperty =
-            PerspexProperty.Register<Image, Bitmap>("Source");
+            PerspexProperty.Register<Image, Bitmap>(nameof(Source));
 
+        /// <summary>
+        /// Defines the <see cref="Stretch"/> property.
+        /// </summary>
         public static readonly PerspexProperty<Stretch> StretchProperty =
-            PerspexProperty.Register<Image, Stretch>("Stretch", Stretch.Uniform);
+            PerspexProperty.Register<Image, Stretch>(nameof(Stretch), Stretch.Uniform);
 
+        /// <summary>
+        /// Gets or sets the bitmap image that will be displayed.
+        /// </summary>
         public Bitmap Source
         {
             get { return this.GetValue(SourceProperty); }
             set { this.SetValue(SourceProperty, value); }
         }
 
-        public Stretch Stretch 
-        { 
+        /// <summary>
+        /// Gets or sets a value controlling how the image will be stretched.
+        /// </summary>
+        public Stretch Stretch
+        {
             get { return (Stretch)this.GetValue(StretchProperty); }
             set { this.SetValue(StretchProperty, value); }
         }
 
-        public override void Render(IDrawingContext drawingContext)
+        /// <summary>
+        /// Renders the control.
+        /// </summary>
+        /// <param name="context">The drawing context.</param>
+        public override void Render(IDrawingContext context)
         {
             Bitmap source = this.Source;
 
@@ -46,10 +65,15 @@ namespace Perspex.Controls
                 Rect sourceRect = new Rect(sourceSize)
                     .CenterIn(new Rect(destRect.Size / scale));
 
-                drawingContext.DrawImage(source, 1, sourceRect, destRect);
+                context.DrawImage(source, 1, sourceRect, destRect);
             }
         }
 
+        /// <summary>
+        /// Measures the control.
+        /// </summary>
+        /// <param name="availableSize">The available size.</param>
+        /// <returns>The desired size of the control.</returns>
         protected override Size MeasureOverride(Size availableSize)
         {
             double width = 0;
@@ -77,11 +101,13 @@ namespace Perspex.Controls
             return new Size(width * scale.X, height * scale.Y);
         }
 
-        protected override Size ArrangeOverride(Size finalSize)
-        {
-            return finalSize;
-        }
-
+        /// <summary>
+        /// Calculates the scaling for the image.
+        /// </summary>
+        /// <param name="availableSize">The size available to display the image.</param>
+        /// <param name="imageSize">The pxiel size of the image.</param>
+        /// <param name="stretch">The stretch mode of the control.</param>
+        /// <returns>A vector with the X and Y scaling factors.</returns>
         private static Vector CalculateScaling(Size availableSize, Size imageSize, Stretch stretch)
         {
             double scaleX = 1;
@@ -106,4 +132,4 @@ namespace Perspex.Controls
             return new Vector(scaleX, scaleY);
         }
     }
-}
+}
\ No newline at end of file
diff --git a/Perspex.Controls/Primitives/AccessText.cs b/Perspex.Controls/Primitives/AccessText.cs
index 6bcf6f6714..a6b8c60167 100644
--- a/Perspex.Controls/Primitives/AccessText.cs
+++ b/Perspex.Controls/Primitives/AccessText.cs
@@ -7,12 +7,10 @@
 namespace Perspex.Controls.Primitives
 {
     using System;
-    using Perspex.Media;
     using Perspex.Input;
+    using Perspex.Media;
     using Perspex.Rendering;
 
-
-
     /// <summary>
     /// A text block that displays a character prefixed with an underscore as an access key.
     /// </summary>
diff --git a/Perspex.Controls/Primitives/HeaderedContentControl.cs b/Perspex.Controls/Primitives/HeaderedContentControl.cs
index bfd9478706..f42ea56bb4 100644
--- a/Perspex.Controls/Primitives/HeaderedContentControl.cs
+++ b/Perspex.Controls/Primitives/HeaderedContentControl.cs
@@ -6,15 +6,24 @@
 
 namespace Perspex.Controls.Primitives
 {
+    /// <summary>
+    /// A <see cref="ContentControl"/> with a header.
+    /// </summary>
     public class HeaderedContentControl : ContentControl, IHeadered
     {
+        /// <summary>
+        /// Defines the <see cref="Header"/> property.
+        /// </summary>
         public static readonly PerspexProperty<object> HeaderProperty =
             PerspexProperty.Register<ContentControl, object>("Header");
 
+        /// <summary>
+        /// Gets or sets the header content.
+        /// </summary>
         public object Header
         {
             get { return this.GetValue(HeaderProperty); }
             set { this.SetValue(HeaderProperty, value); }
         }
     }
-}
+}
\ No newline at end of file
diff --git a/Perspex.Controls/Primitives/SelectingItemsControl.cs b/Perspex.Controls/Primitives/SelectingItemsControl.cs
index 5c1d18f8b3..99bfce60e7 100644
--- a/Perspex.Controls/Primitives/SelectingItemsControl.cs
+++ b/Perspex.Controls/Primitives/SelectingItemsControl.cs
@@ -7,13 +7,13 @@
 namespace Perspex.Controls.Primitives
 {
     using System;
-    using System.Linq;
     using System.Collections;
     using System.Collections.Specialized;
+    using System.Linq;
     using Perspex.Controls.Utils;
     using Perspex.Input;
-    using Perspex.VisualTree;
     using Perspex.Interactivity;
+    using Perspex.VisualTree;
 
     /// <summary>
     /// An <see cref="ItemsControl"/> that maintains a selection.
diff --git a/Perspex.Controls/TextBlock.cs b/Perspex.Controls/TextBlock.cs
index 911ed1727e..1700ae990a 100644
--- a/Perspex.Controls/TextBlock.cs
+++ b/Perspex.Controls/TextBlock.cs
@@ -1,6 +1,6 @@
 // -----------------------------------------------------------------------
 // <copyright file="TextBlock.cs" company="Steven Kirk">
-// Copyright 2014 MIT Licence. See licence.md for more information.
+// Copyright 2015 MIT Licence. See licence.md for more information.
 // </copyright>
 // -----------------------------------------------------------------------
 
@@ -26,49 +26,61 @@ namespace Perspex.Controls
         /// Defines the <see cref="FontFamily"/> property.
         /// </summary>
         public static readonly PerspexProperty<string> FontFamilyProperty =
-            PerspexProperty.RegisterAttached<TextBlock, Control, string>("FontFamily", inherits: true);
+            PerspexProperty.RegisterAttached<TextBlock, Control, string>(
+                nameof(FontFamily),
+                inherits: true);
 
         /// <summary>
         /// Defines the <see cref="FontSize"/> property.
         /// </summary>
         public static readonly PerspexProperty<double> FontSizeProperty =
-            PerspexProperty.RegisterAttached<TextBlock, Control, double>("FontSize", inherits: true);
+            PerspexProperty.RegisterAttached<TextBlock, Control, double>(
+                nameof(FontSize),
+                inherits: true);
 
         /// <summary>
         /// Defines the <see cref="FontStyle"/> property.
         /// </summary>
         public static readonly PerspexProperty<FontStyle> FontStyleProperty =
-            PerspexProperty.RegisterAttached<TextBlock, Control, FontStyle>("FontStyle", inherits: true);
+            PerspexProperty.RegisterAttached<TextBlock, Control, FontStyle>(
+                nameof(FontStyle),
+                inherits: true);
 
         /// <summary>
         /// Defines the <see cref="FontWeight"/> property.
         /// </summary>
         public static readonly PerspexProperty<FontWeight> FontWeightProperty =
-            PerspexProperty.RegisterAttached<TextBlock, Control, FontWeight>("FontWeight", inherits: true, defaultValue: FontWeight.Normal);
+            PerspexProperty.RegisterAttached<TextBlock, Control, FontWeight>(
+                nameof(FontWeight),
+                inherits: true,
+                defaultValue: FontWeight.Normal);
 
         /// <summary>
         /// Defines the <see cref="Foreground"/> property.
         /// </summary>
         public static readonly PerspexProperty<Brush> ForegroundProperty =
-            PerspexProperty.RegisterAttached<TextBlock, Control, Brush>("Foreground", new SolidColorBrush(0xff000000), inherits: true);
+            PerspexProperty.RegisterAttached<TextBlock, Control, Brush>(
+                nameof(Foreground),
+                new SolidColorBrush(0xff000000),
+                inherits: true);
 
         /// <summary>
         /// Defines the <see cref="Text"/> property.
         /// </summary>
         public static readonly PerspexProperty<string> TextProperty =
-            PerspexProperty.Register<TextBlock, string>("Text");
+            PerspexProperty.Register<TextBlock, string>(nameof(Text));
 
         /// <summary>
         /// Defines the <see cref="TextAlignment"/> property.
         /// </summary>
         public static readonly PerspexProperty<TextAlignment> TextAlignmentProperty =
-            PerspexProperty.Register<TextBlock, TextAlignment>("TextAlignment");
+            PerspexProperty.Register<TextBlock, TextAlignment>(nameof(TextAlignment));
 
         /// <summary>
         /// Defines the <see cref="TextWrapping"/> property.
         /// </summary>
         public static readonly PerspexProperty<TextWrapping> TextWrappingProperty =
-            PerspexProperty.Register<TextBlock, TextWrapping>("TextWrapping");
+            PerspexProperty.Register<TextBlock, TextWrapping>(nameof(TextWrapping));
 
         /// <summary>
         /// The formatted text used for rendering.
@@ -80,6 +92,14 @@ namespace Perspex.Controls
         /// </summary>
         private Size constraint;
 
+        /// <summary>
+        /// Initializes static members of the <see cref="TextBlock"/> class.
+        /// </summary>
+        static TextBlock()
+        {
+            AffectsRender(ForegroundProperty);
+        }
+
         /// <summary>
         /// Initializes a new instance of the <see cref="TextBlock"/> class.
         /// </summary>
@@ -207,7 +227,7 @@ namespace Perspex.Controls
             }
 
             this.FormattedText.Constraint = this.Bounds.Size;
-            context.DrawText(this.Foreground,  new Point(), this.FormattedText);
+            context.DrawText(this.Foreground, new Point(), this.FormattedText);
         }
 
         /// <summary>
@@ -267,4 +287,4 @@ namespace Perspex.Controls
             return new Size();
         }
     }
-}
+}
\ No newline at end of file
diff --git a/Perspex.Controls/TextWrapping.cs b/Perspex.Controls/TextWrapping.cs
index f23281d047..4fcacfc8ad 100644
--- a/Perspex.Controls/TextWrapping.cs
+++ b/Perspex.Controls/TextWrapping.cs
@@ -1,14 +1,24 @@
 // -----------------------------------------------------------------------
 // <copyright file="TextWrapping.cs" company="Steven Kirk">
-// Copyright 2014 MIT Licence. See licence.md for more information.
+// Copyright 2015 MIT Licence. See licence.md for more information.
 // </copyright>
 // -----------------------------------------------------------------------
 
 namespace Perspex.Controls
 {
+    /// <summary>
+    /// Controls the wrapping mode in a <see cref="TextBlock"/>.
+    /// </summary>
     public enum TextWrapping
     {
+        /// <summary>
+        /// Text should not wrap.
+        /// </summary>
         NoWrap,
+
+        /// <summary>
+        /// Text can wrap.
+        /// </summary>
         Wrap
     }
-}
+}
\ No newline at end of file