updated docs for Dim and Pos

Terminal.Gui/Types/PosDim.cs

@@ -8,25 +8,25 @@
 using System;
 namespace Terminal.Gui {
 	/// <summary>
-	/// Describes a position which can be an absolute value, a percentage, centered, or 
-	/// relative to the ending dimension.   Integer values are implicitly convertible to
-	/// an absolute Pos.    These objects are created using the static methods Percent,
-	/// AnchorEnd and Center.   The Pos objects can be combined with the addition and 
+	/// Describes the position of a <see cref="View"/> which can be an absolute value, a percentage, centered, or 
+	/// relative to the ending dimension. Integer values are implicitly convertible to
+	/// an absolute <see cref="Pos"/>. These objects are created using the static methods Percent,
+	/// AnchorEnd, and Center. The <see cref="Pos"/> objects can be combined with the addition and 
 	/// subtraction operators.
 	/// </summary>
 	/// <remarks>
 	///   <para>
-	///     Use the Pos objects on the X or Y properties of a view to control the position.
+	///     Use the <see cref="Pos"/> objects on the X or Y properties of a view to control the position.
 	///   </para>
 	///   <para>
 	///     These can be used to set the absolute position, when merely assigning an
-	///     integer value (via the implicit integer to Pos conversion), and they can be combined
+	///     integer value (via the implicit integer to <see cref="Pos"/> conversion), and they can be combined
 	///     to produce more useful layouts, like: Pos.Center - 3, which would shift the postion
-	///     of the view 3 characters to the left after centering for example.
+	///     of the <see cref="View"/> 3 characters to the left after centering for example.
 	///   </para>
 	///   <para>
 	///     It is possible to reference coordinates of another view by using the methods
-	///     Left(View), Right(View), Bottom(View), Top(View).   The X(View) and Y(View) are
+	///     Left(View), Right(View), Bottom(View), Top(View). The X(View) and Y(View) are
 	///     aliases to Left(View) and Top(View) respectively.
 	///   </para>
 	/// </remarks>
@@ -56,10 +56,22 @@ namespace Terminal.Gui {
 		}
 
 		/// <summary>
-		/// Creates a percentage Pos object
+		/// Creates a percentage <see cref="Pos"/> object
 		/// </summary>
-		/// <returns>The percent Pos object.</returns>
+		/// <returns>The percent <see cref="Pos"/> object.</returns>
 		/// <param name="n">A value between 0 and 100 representing the percentage.</param>
+		/// <example>
+		/// This creates a <see cref="TextField"/>that is centered horizontally, is 50% of the way down, 
+		/// is 30% the height, and is 80% the width of the <see cref="View"/> it added to.
+		/// <code>
+		/// var textView = new TextView () {
+		///	X = Pos.Center (),
+		///	Y = Pos.Percent (50),
+		///	Width = Dim.Percent (80),
+		/// 	Height = Dim.Percent (30),
+		/// };
+		/// </code>
+		/// </example>
 		public static Pos Percent (float n)
 		{
 			if (n < 0 || n > 100)
@@ -90,11 +102,18 @@ namespace Terminal.Gui {
 		}
 
 		/// <summary>
-		/// Creates a Pos object that is anchored to the end of the dimension, useful to flush 
-		/// the layout from the end.
+		/// Creates a <see cref="Pos"/> object that is anchored to the end (right side or bottom) of the dimension, 
+		/// useful to flush the layout from the right or bottom.
 		/// </summary>
-		/// <returns>The Pos object anchored to the end (the bottom or the right side).</returns>
-		/// <param name="margin">Optional margin to set aside.</param>
+		/// <returns>The <see cref="Pos"/> object anchored to the end (the bottom or the right side).</returns>
+		/// <param name="margin">Optional margin to place to the right or below.</param>
+		/// <example>
+		/// This sample shows how align a <see cref="Button"/> to the bottom-right of a <see cref="View"/>.
+		/// <code>
+		/// anchorButton.X = Pos.AnchorEnd () - (Pos.Right (anchorButton) - Pos.Left (anchorButton));
+		/// anchorButton.Y = Pos.AnchorEnd () - 1;
+		/// </code>
+		/// </example>
 		public static Pos AnchorEnd (int margin = 0)
 		{
 			if (margin < 0)
@@ -123,9 +142,21 @@ namespace Terminal.Gui {
 		static PosCenter pCenter;
 
 		/// <summary>
-		/// Returns a Pos object that can be used to center the views.
+		/// Returns a <see cref="Pos"/> object that can be used to center the <see cref="View"/>
 		/// </summary>
 		/// <returns>The center Pos.</returns>
+		/// <example>
+		/// This creates a <see cref="TextField"/>that is centered horizontally, is 50% of the way down, 
+		/// is 30% the height, and is 80% the width of the <see cref="View"/> it added to.
+		/// <code>
+		/// var textView = new TextView () {
+		///	X = Pos.Center (),
+		///	Y = Pos.Percent (50),
+		///	Width = Dim.Percent (80),
+		/// 	Height = Dim.Percent (30),
+		/// };
+		/// </code>
+		/// </example>
 		public static Pos Center ()
 		{
 			if (pCenter == null)
@@ -149,20 +180,20 @@ namespace Terminal.Gui {
 		}
 
 		/// <summary>
-		/// Creates an Absolute Pos from the specified integer value.
+		/// Creates an Absolute <see cref="Pos"/> from the specified integer value.
 		/// </summary>
-		/// <returns>The Absolute Pos.</returns>
-		/// <param name="n">The value to convert to the pos.</param>
+		/// <returns>The Absolute <see cref="Pos"/>.</returns>
+		/// <param name="n">The value to convert to the <see cref="Pos"/> .</param>
 		public static implicit operator Pos (int n)
 		{
 			return new PosAbsolute (n);
 		}
 
 		/// <summary>
-		/// Creates an Absolute Pos from the specified integer value.
+		/// Creates an Absolute <see cref="Pos"/> from the specified integer value.
 		/// </summary>
-		/// <returns>The Absolute Pos.</returns>
-		/// <param name="n">The value to convert to the pos.</param>
+		/// <returns>The Absolute <see cref="Pos"/>.</returns>
+		/// <param name="n">The value to convert to the <see cref="Pos"/>.</param>
 		public static Pos At (int n)
 		{
 			return new PosAbsolute (n);
@@ -190,7 +221,7 @@ namespace Terminal.Gui {
 
 			public override string ToString ()
 			{
-				return $"Pos.Combine ({left.ToString ()}{(add?'+':'-')}{right.ToString ()})";
+				return $"Pos.Combine ({left.ToString ()}{(add ? '+' : '-')}{right.ToString ()})";
 			}
 
 		}
@@ -262,65 +293,65 @@ namespace Terminal.Gui {
 				case 3: tside = "bottom"; break;
 				default: tside = "unknown"; break;
 				}
-				return $"Pos.View(side={tside}, target={Target.ToString()}";
+				return $"Pos.View(side={tside}, target={Target.ToString ()}";
 			}
 		}
 
 		/// <summary>
-		/// Returns a Pos object tracks the Left (X) position of the specified view.
+		/// Returns a <see cref="Pos"/> object tracks the Left (X) position of the specified <see cref="View"/>.
 		/// </summary>
-		/// <returns>The Position that depends on the other view.</returns>
-		/// <param name="view">The view that will be tracked.</param>
+		/// <returns>The <see cref="Pos"/> that depends on the other view.</returns>
+		/// <param name="view">The <see cref="View"/>  that will be tracked.</param>
 		public static Pos Left (View view) => new PosView (view, 0);
 
 		/// <summary>
-		/// Returns a Pos object tracks the Left (X) position of the specified view.
+		/// Returns a <see cref="Pos"/> object tracks the Left (X) position of the specified <see cref="View"/>.
 		/// </summary>
-		/// <returns>The Position that depends on the other view.</returns>
-		/// <param name="view">The view that will be tracked.</param>
+		/// <returns>The <see cref="Pos"/> that depends on the other view.</returns>
+		/// <param name="view">The <see cref="View"/>  that will be tracked.</param>
 		public static Pos X (View view) => new PosView (view, 0);
 
 		/// <summary>
-		/// Returns a Pos object tracks the Top (Y) position of the specified view.
+		/// Returns a <see cref="Pos"/> object tracks the Top (Y) position of the specified <see cref="View"/>.
 		/// </summary>
-		/// <returns>The Position that depends on the other view.</returns>
-		/// <param name="view">The view that will be tracked.</param>
+		/// <returns>The <see cref="Pos"/> that depends on the other view.</returns>
+		/// <param name="view">The <see cref="View"/>  that will be tracked.</param>
 		public static Pos Top (View view) => new PosView (view, 1);
 
 		/// <summary>
-		/// Returns a Pos object tracks the Top (Y) position of the specified view.
+		/// Returns a <see cref="Pos"/> object tracks the Top (Y) position of the specified <see cref="View"/>.
 		/// </summary>
-		/// <returns>The Position that depends on the other view.</returns>
-		/// <param name="view">The view that will be tracked.</param>
+		/// <returns>The <see cref="Pos"/> that depends on the other view.</returns>
+		/// <param name="view">The <see cref="View"/>  that will be tracked.</param>
 		public static Pos Y (View view) => new PosView (view, 1);
 
 		/// <summary>
-		/// Returns a Pos object tracks the Right (X+Width) coordinate of the specified view.
+		/// Returns a <see cref="Pos"/> object tracks the Right (X+Width) coordinate of the specified <see cref="View"/>.
 		/// </summary>
-		/// <returns>The Position that depends on the other view.</returns>
-		/// <param name="view">The view that will be tracked.</param>
+		/// <returns>The <see cref="Pos"/> that depends on the other view.</returns>
+		/// <param name="view">The <see cref="View"/>  that will be tracked.</param>
 		public static Pos Right (View view) => new PosView (view, 2);
 
 		/// <summary>
-		/// Returns a Pos object tracks the Bottom (Y+Height) coordinate of the specified view.
+		/// Returns a <see cref="Pos"/> object tracks the Bottom (Y+Height) coordinate of the specified <see cref="View"/> 
 		/// </summary>
-		/// <returns>The Position that depends on the other view.</returns>
-		/// <param name="view">The view that will be tracked.</param>
+		/// <returns>The <see cref="Pos"/> that depends on the other view.</returns>
+		/// <param name="view">The <see cref="View"/>  that will be tracked.</param>
 		public static Pos Bottom (View view) => new PosView (view, 3);
 	}
 
 	/// <summary>
-	/// Dim properties of a view to control the position.
+	/// Dim properties of a <see cref="View"/> to control the position.
 	/// </summary>
 	/// <remarks>
 	///   <para>
-	///     Use the Dim objects on the Width or Height properties of a view to control the position.
+	///     Use the Dim objects on the Width or Height properties of a <see cref="View"/> to control the position.
 	///   </para>
 	///   <para>
 	///     These can be used to set the absolute position, when merely assigning an
 	///     integer value (via the implicit integer to Pos conversion), and they can be combined
 	///     to produce more useful layouts, like: Pos.Center - 3, which would shift the postion
-	///     of the view 3 characters to the left after centering for example.
+	///     of the <see cref="View"/> 3 characters to the left after centering for example.
 	///   </para>
 	/// </remarks>
 	public class Dim {
@@ -347,17 +378,29 @@ namespace Terminal.Gui {
 				return $"Dim.Factor({factor})";
 			}
 
-			public override int GetHashCode () => factor.GetHashCode();
+			public override int GetHashCode () => factor.GetHashCode ();
 
 			public override bool Equals (object other) => other is DimFactor f && f.factor == factor;
 
 		}
 
 		/// <summary>
-		/// Creates a percentage Dim object
+		/// Creates a percentage <see cref="Dim"/> object
 		/// </summary>
-		/// <returns>The percent Dim object.</returns>
+		/// <returns>The percent <see cref="Dim"/> object.</returns>
 		/// <param name="n">A value between 0 and 100 representing the percentage.</param>
+		/// <example>
+		/// This creates a <see cref="TextField"/>that is centered horizontally, is 50% of the way down, 
+		/// is 30% the height, and is 80% the width of the <see cref="View"/> it added to.
+		/// <code>
+		/// var textView = new TextView () {
+		///	X = Pos.Center (),
+		///	Y = Pos.Percent (50),
+		///	Width = Dim.Percent (80),
+		/// 	Height = Dim.Percent (30),
+		/// };
+		/// </code>
+		/// </example>
 		public static Dim Percent (float n)
 		{
 			if (n < 0 || n > 100)
@@ -380,7 +423,7 @@ namespace Terminal.Gui {
 				return n;
 			}
 
-			public override int GetHashCode () => n.GetHashCode();
+			public override int GetHashCode () => n.GetHashCode ();
 
 			public override bool Equals (object other) => other is DimAbsolute abs && abs.n == n;
 
@@ -397,10 +440,10 @@ namespace Terminal.Gui {
 
 			internal override int Anchor (int width)
 			{
-				return width-margin;
+				return width - margin;
 			}
 
-			public override int GetHashCode () => margin.GetHashCode();
+			public override int GetHashCode () => margin.GetHashCode ();
 
 			public override bool Equals (object other) => other is DimFill fill && fill.margin == margin;
 		}
@@ -408,7 +451,7 @@ namespace Terminal.Gui {
 		static DimFill zeroMargin;
 
 		/// <summary>
-		/// Creates a Dim object that fills the dimension, but leaves the specified number of colums for a margin.
+		/// Creates a <see cref="Dim"/> object that fills the dimension, but leaves the specified number of colums for a margin.
 		/// </summary>
 		/// <returns>The Fill dimension.</returns>
 		/// <param name="margin">Margin to use.</param>
@@ -423,9 +466,9 @@ namespace Terminal.Gui {
 		}
 
 		/// <summary>
-		/// Creates an Absolute Pos from the specified integer value.
+		/// Creates an Absolute <see cref="Dim"/> from the specified integer value.
 		/// </summary>
-		/// <returns>The Absolute Pos.</returns>
+		/// <returns>The Absolute <see cref="Dim"/>.</returns>
 		/// <param name="n">The value to convert to the pos.</param>
 		public static implicit operator Dim (int n)
 		{
@@ -433,10 +476,10 @@ namespace Terminal.Gui {
 		}
 
 		/// <summary>
-		/// Creates an Absolute Pos from the specified integer value.
+		/// Creates an Absolute <see cref="Dim"/> from the specified integer value.
 		/// </summary>
-		/// <returns>The Absolute Pos.</returns>
-		/// <param name="n">The value to convert to the pos.</param>
+		/// <returns>The Absolute <see cref="Dim"/>.</returns>
+		/// <param name="n">The value to convert to the <see cref="Dim"/>.</param>
 		public static Dim Sized (int n)
 		{
 			return new DimAbsolute (n);
@@ -464,22 +507,22 @@ namespace Terminal.Gui {
 		}
 
 		/// <summary>
-		/// Adds a <see cref="Terminal.Gui.Pos"/> to a <see cref="Terminal.Gui.Pos"/>, yielding a new <see cref="T:Terminal.Gui.Pos"/>.
+		/// Adds a <see cref="Terminal.Gui.Dim"/> to a <see cref="Terminal.Gui.Dim"/>, yielding a new <see cref="T:Terminal.Gui.Dim"/>.
 		/// </summary>
-		/// <param name="left">The first <see cref="Terminal.Gui.Pos"/> to add.</param>
-		/// <param name="right">The second <see cref="Terminal.Gui.Pos"/> to add.</param>
-		/// <returns>The <see cref="T:Terminal.Gui.Pos"/> that is the sum of the values of <c>left</c> and <c>right</c>.</returns>
+		/// <param name="left">The first <see cref="Terminal.Gui.Dim"/> to add.</param>
+		/// <param name="right">The second <see cref="Terminal.Gui.Dim"/> to add.</param>
+		/// <returns>The <see cref="T:Terminal.Gui.Dim"/> that is the sum of the values of <c>left</c> and <c>right</c>.</returns>
 		public static Dim operator + (Dim left, Dim right)
 		{
 			return new DimCombine (true, left, right);
 		}
 
 		/// <summary>
-		/// Subtracts a <see cref="Terminal.Gui.Pos"/> from a <see cref="Terminal.Gui.Pos"/>, yielding a new <see cref="T:Terminal.Gui.Pos"/>.
+		/// Subtracts a <see cref="Terminal.Gui.Dim"/> from a <see cref="Terminal.Gui.Dim"/>, yielding a new <see cref="T:Terminal.Gui.Dim"/>.
 		/// </summary>
-		/// <param name="left">The <see cref="Terminal.Gui.Pos"/> to subtract from (the minuend).</param>
-		/// <param name="right">The <see cref="Terminal.Gui.Pos"/> to subtract (the subtrahend).</param>
-		/// <returns>The <see cref="T:Terminal.Gui.Pos"/> that is the <c>left</c> minus <c>right</c>.</returns>
+		/// <param name="left">The <see cref="Terminal.Gui.Dim"/> to subtract from (the minuend).</param>
+		/// <param name="right">The <see cref="Terminal.Gui.Dim"/> to subtract (the subtrahend).</param>
+		/// <returns>The <see cref="T:Terminal.Gui.Dim"/> that is the <c>left</c> minus <c>right</c>.</returns>
 		public static Dim operator - (Dim left, Dim right)
 		{
 			return new DimCombine (false, left, right);
@@ -505,16 +548,16 @@ namespace Terminal.Gui {
 			}
 		}
 		/// <summary>
-		/// Returns a Dim object tracks the Width of the specified view.
+		/// Returns a <see cref="Dim"/> object tracks the Width of the specified <see cref="View"/>.
 		/// </summary>
-		/// <returns>The dimension of the other view.</returns>
+		/// <returns>The <see cref="Dim"/> of the other <see cref="View"/>.</returns>
 		/// <param name="view">The view that will be tracked.</param>
 		public static Dim Width (View view) => new DimView (view, 1);
 
 		/// <summary>
-		/// Returns a Dim object tracks the Height of the specified view.
+		/// Returns a <see cref="Dim"/> object tracks the Height of the specified <see cref="View"/>.
 		/// </summary>
-		/// <returns>The dimension of the other view.</returns>
+		/// <returns>The <see cref="Dim"/> of the other <see cref="View"/>.</returns>
 		/// <param name="view">The view that will be tracked.</param>
 		public static Dim Height (View view) => new DimView (view, 0);
 	}