PosDim code clean up and APIU doc improvements

Terminal.Gui/View/Layout/PosDim.cs

@@ -1,84 +1,83 @@
+using System.ComponentModel;
 using System.Diagnostics;
 using static Terminal.Gui.Dim;
 
 namespace Terminal.Gui;
 
 /// <summary>
-///     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.
+///     Describes the horizontal or vertical position of a <see cref="View"/>. The position can be an absolute value,
+///     a percentage, centered, a function, relative to the ending dimension, relative to another View, or aligned with a
+///     set of views.
+///     Integer values are implicitly convertible to an absolute <see cref="Pos"/>. <see cref="Pos"/>
+///     objects are created using the static methods provided (e.g. <see cref="Percent"/> and <see cref="Center"/>).
+///     The <see cref="Pos"/> objects can be combined with the addition and subtraction operators.
 /// </summary>
 /// <remarks>
-///     <para>Use the <see cref="Pos"/> objects on the X or Y properties of a view to control the position.</para>
+///     <para>Use the <see cref="Pos"/> objects on the X or Y 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 <see cref="Pos"/> conversion), and they can be combined to produce more useful layouts, like:
-///         Pos.Center - 3, which would shift the position of the <see cref="View"/> 3 characters to the left after
+///         <c>Pos.Center - 3</c>, which would shift the position of the <see cref="View"/> 3 characters to the left after
 ///         centering for example.
 ///     </para>
 ///     <para>
-///         Reference coordinates of another view by using the methods Left(View), Right(View), Bottom(View), Top(View).
-///         The X(View) and Y(View) are aliases to Left(View) and Top(View) respectively.
-///     </para>
-///     <para>
 ///         <list type="table">
 ///             <listheader>
 ///                 <term>Pos Object</term> <description>Description</description>
 ///             </listheader>
 ///             <item>
 ///                 <term>
-///                     <see cref="Pos.Function(Func{int})"/>
+///                     <see cref="Pos.Align"/>
 ///                 </term>
 ///                 <description>
-///                     Creates a <see cref="Pos"/> object that computes the position by executing the provided
-///                     function. The function will be called every time the position is needed.
+///                     Creates a <see cref="Pos"/> object that aligns a set of views.
 ///                 </description>
 ///             </item>
 ///             <item>
 ///                 <term>
-///                     <see cref="Pos.Percent(float)"/>
+///                     <see cref="Pos.AnchorEnd()"/>
 ///                 </term>
 ///                 <description>
-///                     Creates a <see cref="Pos"/> object that is a percentage of the width or height of the
-///                     SuperView.
+///                     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.
 ///                 </description>
 ///             </item>
 ///             <item>
 ///                 <term>
-///                     <see cref="Pos.Align()"/>
+///                     <see cref="Pos.At(int)"/>
 ///                 </term>
 ///                 <description>
-///                     Creates a <see cref="Pos"/> object that aligns a set of views.
+///                     Creates a <see cref="Pos"/> object that is an absolute position based on the specified
+///                     integer.
 ///                 </description>
 ///             </item>
 ///             <item>
 ///                 <term>
-///                     <see cref="Pos.AnchorEnd()"/>
+///                     <see cref="Pos.Center"/>
 ///                 </term>
-///                 <description>
-///                     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.
-///                 </description>
+///                 <description>Creates a <see cref="Pos"/> object that can be used to center the <see cref="View"/>.</description>
 ///             </item>
 ///             <item>
 ///                 <term>
-///                     <see cref="Pos.Center"/>
+///                     <see cref="Pos.Function(Func{int})"/>
 ///                 </term>
-///                 <description>Creates a <see cref="Pos"/> object that can be used to center the <see cref="View"/>.</description>
+///                 <description>
+///                     Creates a <see cref="Pos"/> object that computes the position by executing the provided
+///                     function. The function will be called every time the position is needed.
+///                 </description>
 ///             </item>
 ///             <item>
 ///                 <term>
-///                     <see cref="Pos.At(int)"/>
+///                     <see cref="Pos.Percent(float)"/>
 ///                 </term>
 ///                 <description>
-///                     Creates a <see cref="Pos"/> object that is an absolute position based on the specified
-///                     integer value.
+///                     Creates a <see cref="Pos"/> object that is a percentage of the width or height of the
+///                     SuperView.
 ///                 </description>
 ///             </item>
 ///             <item>
 ///                 <term>
-///                     <see cref="Pos.Left"/>
+///                     <see cref="Pos.Left(View)"/>
 ///                 </term>
 ///                 <description>
 ///                     Creates a <see cref="Pos"/> object that tracks the Left (X) position of the specified
@@ -135,6 +134,8 @@ namespace Terminal.Gui;
 /// </remarks>
 public class Pos
 {
+    #region Static Methods - Create Pos objects
+
     /// <summary>
     ///     Creates a <see cref="Pos"/> object that is anchored to the end (right side or
     ///     bottom) of the SuperView, minus the respective dimension of the View. This is equivalent to using
@@ -196,14 +197,6 @@ public class Pos
     /// </example>
     public static Pos Center () { return new PosCenter (); }
 
-    /// <summary>Determines whether the specified object is equal to the current object.</summary>
-    /// <param name="other">The object to compare with the current object. </param>
-    /// <returns>
-    ///     <see langword="true"/> if the specified object  is equal to the current object; otherwise,
-    ///     <see langword="false"/>.
-    /// </returns>
-    public override bool Equals (object other) { return other is Pos abs && abs == this; }
-
     /// <summary>
     ///     Creates a <see cref="Pos"/> object that computes the position by executing the provided function. The function
     ///     will be called every time the position is needed.
@@ -212,69 +205,17 @@ public class Pos
     /// <returns>The <see cref="Pos"/> returned from the function.</returns>
     public static Pos Function (Func<int> function) { return new PosFunc (function); }
 
-
     /// <summary>
-    ///      Creates a <see cref="Pos"/> object that aligns a set of views according to the specified alignment setting.
+    ///     Creates a <see cref="Pos"/> object that aligns a set of views according to the specified alignment setting.
     /// </summary>
     /// <param name="alignment"></param>
-    /// <param name="groupId">The optional, unique identifier for the set of views to align according to <paramref name="alignment"/>.</param>
+    /// <param name="groupId">
+    ///     The optional, unique identifier for the set of views to align according to
+    ///     <paramref name="alignment"/>.
+    /// </param>
     /// <returns></returns>
     public static Pos Align (Alignment alignment, int groupId = 0) { return new PosAlign (alignment, groupId); }
 
-    /// <summary>Serves as the default hash function. </summary>
-    /// <returns>A hash code for the current object.</returns>
-    public override int GetHashCode () { return Anchor (0).GetHashCode (); }
-
-    /// <summary>Adds a <see cref="Terminal.Gui.Pos"/> to a <see cref="Terminal.Gui.Pos"/>, yielding a new <see cref="Pos"/>.</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="Pos"/> that is the sum of the values of <c>left</c> and <c>right</c>.</returns>
-    public static Pos operator + (Pos left, Pos right)
-    {
-        if (left is PosAbsolute && right is PosAbsolute)
-        {
-            return new PosAbsolute (left.Anchor (0) + right.Anchor (0));
-        }
-
-        var newPos = new PosCombine (true, left, right);
-
-        if (left is PosView view)
-        {
-            view.Target.SetNeedsLayout ();
-        }
-
-        return newPos;
-    }
-
-    /// <summary>Creates an Absolute <see cref="Pos"/> from the specified integer value.</summary>
-    /// <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>
-    ///     Subtracts a <see cref="Terminal.Gui.Pos"/> from a <see cref="Terminal.Gui.Pos"/>, yielding a new
-    ///     <see cref="Pos"/>.
-    /// </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="Pos"/> that is the <c>left</c> minus <c>right</c>.</returns>
-    public static Pos operator - (Pos left, Pos right)
-    {
-        if (left is PosAbsolute && right is PosAbsolute)
-        {
-            return new PosAbsolute (left.Anchor (0) - right.Anchor (0));
-        }
-
-        var newPos = new PosCombine (false, left, right);
-
-        if (left is PosView view)
-        {
-            view.Target.SetNeedsLayout ();
-        }
-
-        return newPos;
-    }
-
     /// <summary>Creates a percentage <see cref="Pos"/> object</summary>
     /// <returns>The percent <see cref="Pos"/> object.</returns>
     /// <param name="percent">A value between 0 and 100 representing the percentage.</param>
@@ -336,8 +277,12 @@ public class Pos
     /// <param name="view">The <see cref="View"/>  that will be tracked.</param>
     public static Pos Right (View view) { return new PosView (view, Side.Right); }
 
+    #endregion Static Methods - Create Pos objects
+
+    #region Methods
+
     /// <summary>
-    ///     Gets a position that is anchored to a certain point in the layout. This method is typically used
+    ///     Gets a position that is anchored to a certain point in the layout. This method is used
     ///     internally by the layout system to determine where a View should be positioned.
     /// </summary>
     /// <param name="width">The width of the area where the View is being positioned (Superview.ContentSize).</param>
@@ -364,21 +309,88 @@ public class Pos
     ///     that
     ///     is used.
     /// </returns>
-    internal virtual int Calculate (int superviewDimension, Dim dim, View us, Dim.Dimension dimension)
+    internal virtual int Calculate (int superviewDimension, Dim dim, View us, Dimension dimension) { return Anchor (superviewDimension); }
+
+    /// <summary>
+    ///     Diagnostics API to determine if this Pos object references other views.
+    /// </summary>
+    /// <returns></returns>
+    internal virtual bool ReferencesOtherViews () { return false; }
+
+    #endregion Methods
+
+    #region Operators
+
+    /// <summary>Adds a <see cref="Terminal.Gui.Pos"/> to a <see cref="Terminal.Gui.Pos"/>, yielding a new <see cref="Pos"/>.</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="Pos"/> that is the sum of the values of <c>left</c> and <c>right</c>.</returns>
+    public static Pos operator + (Pos left, Pos right)
     {
-        return Anchor (superviewDimension);
+        if (left is PosAbsolute && right is PosAbsolute)
+        {
+            return new PosAbsolute (left.Anchor (0) + right.Anchor (0));
+        }
+
+        var newPos = new PosCombine (true, left, right);
+
+        if (left is PosView view)
+        {
+            view.Target.SetNeedsLayout ();
+        }
+
+        return newPos;
     }
 
+    /// <summary>Creates an Absolute <see cref="Pos"/> from the specified integer value.</summary>
+    /// <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>
-    /// Diagnostics API to determine if this Pos object references other views.
+    ///     Subtracts a <see cref="Terminal.Gui.Pos"/> from a <see cref="Terminal.Gui.Pos"/>, yielding a new
+    ///     <see cref="Pos"/>.
     /// </summary>
-    /// <returns></returns>
-    internal virtual bool ReferencesOtherViews ()
+    /// <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="Pos"/> that is the <c>left</c> minus <c>right</c>.</returns>
+    public static Pos operator - (Pos left, Pos right)
     {
-        return false;
+        if (left is PosAbsolute && right is PosAbsolute)
+        {
+            return new PosAbsolute (left.Anchor (0) - right.Anchor (0));
+        }
+
+        var newPos = new PosCombine (false, left, right);
+
+        if (left is PosView view)
+        {
+            view.Target.SetNeedsLayout ();
+        }
+
+        return newPos;
     }
 
+    #endregion
+
+    #region Overrides
+
+    /// <summary>Determines whether the specified object is equal to the current object.</summary>
+    /// <param name="other">The object to compare with the current object. </param>
+    /// <returns>
+    ///     <see langword="true"/> if the specified object  is equal to the current object; otherwise,
+    ///     <see langword="false"/>.
+    /// </returns>
+    public override bool Equals (object other) { return other is Pos abs && abs == this; }
+
+    /// <summary>Serves as the default hash function. </summary>
+    /// <returns>A hash code for the current object.</returns>
+    public override int GetHashCode () { return Anchor (0).GetHashCode (); }
+
+    #endregion Overrides
+
+    #region Pos Types
+    // TODO: These should not be nested classes - extract them.
     internal class PosAbsolute (int n) : Pos
     {
         private readonly int _n = n;
@@ -413,7 +425,7 @@ public class Pos
             return width - _offset;
         }
 
-        internal override int Calculate (int superviewDimension, Dim dim, View us, Dim.Dimension dimension)
+        internal override int Calculate (int superviewDimension, Dim dim, View us, Dimension dimension)
         {
             int newLocation = Anchor (superviewDimension);
 
@@ -431,7 +443,7 @@ public class Pos
         public override string ToString () { return "Center"; }
         internal override int Anchor (int width) { return width / 2; }
 
-        internal override int Calculate (int superviewDimension, Dim dim, View us, Dim.Dimension dimension)
+        internal override int Calculate (int superviewDimension, Dim dim, View us, Dimension dimension)
         {
             int newDimension = Math.Max (dim.Calculate (0, superviewDimension, us, dimension), 0);
 
@@ -459,7 +471,7 @@ public class Pos
             return la - ra;
         }
 
-        internal override int Calculate (int superviewDimension, Dim dim, View us, Dim.Dimension dimension)
+        internal override int Calculate (int superviewDimension, Dim dim, View us, Dimension dimension)
         {
             int newDimension = dim.Calculate (0, superviewDimension, us, dimension);
             int left = _left.Calculate (superviewDimension, dim, us, dimension);
@@ -474,7 +486,7 @@ public class Pos
         }
 
         /// <summary>
-        /// Diagnostics API to determine if this Pos object references other views.
+        ///     Diagnostics API to determine if this Pos object references other views.
         /// </summary>
         /// <returns></returns>
         internal override bool ReferencesOtherViews ()
@@ -502,54 +514,55 @@ public class Pos
         internal override int Anchor (int width) { return (int)(width * _factor); }
     }
 
-
     /// <summary>
-    /// Enables alignment of a set of views.
+    ///     Enables alignment of a set of views.
     /// </summary>
     /// <remarks>
-    /// <para>
-    ///     The Group ID is used to identify a set of views that should be alignment together. When only a single
-    ///     set of views is aligned, setting the Group ID is not needed because it defaults to 0.
-    /// </para>
-    /// <para>
-    ///     The first view added to the Superview with a given Group ID is used to determine the alignment of the group.
-    ///     The alignment is applied to all views with the same Group ID.
-    /// </para>
+    ///     <para>
+    ///         The Group ID is used to identify a set of views that should be alignment together. When only a single
+    ///         set of views is aligned, setting the Group ID is not needed because it defaults to 0.
+    ///     </para>
+    ///     <para>
+    ///         The first view added to the Superview with a given Group ID is used to determine the alignment of the group.
+    ///         The alignment is applied to all views with the same Group ID.
+    ///     </para>
     /// </remarks>
     public class PosAlign : Pos
     {
+        // BUGBUG: PosAlign should be internal like all other Pos classes. It is public because the PosAlign Scenario uses it. Refactor that Scenario.
         /// <summary>
-        /// The cached location. Used to store the calculated location to avoid recalculating it.
+        ///     The cached location. Used to store the calculated location to avoid recalculating it.
         /// </summary>
         private int? _location;
 
         /// <summary>
-        /// Gets the identifier of a set of views that should be aligned together. When only a single
-        /// set of views is aligned, setting the <see cref="_groupId"/> is not needed because it defaults to 0.
+        ///     Gets the identifier of a set of views that should be aligned together. When only a single
+        ///     set of views is aligned, setting the <see cref="_groupId"/> is not needed because it defaults to 0.
         /// </summary>
         private readonly int _groupId;
 
         /// <summary>
-        /// Gets the alignment settings.
+        ///     Gets the alignment settings.
         /// </summary>
         public Aligner Aligner { get; } = new ();
 
-
         /// <summary>
-        /// Aligns the views in <paramref name="views"/> that have the same group ID as <paramref name="groupId"/>.
+        ///     Aligns the views in <paramref name="views"/> that have the same group ID as <paramref name="groupId"/>.
         /// </summary>
         /// <param name="groupId"></param>
         /// <param name="views"></param>
         /// <param name="dimension"></param>
         /// <param name="size"></param>
-        private static void AlignGroup (int groupId, IList<View> views, Dim.Dimension dimension, int size)
+        private static void AlignGroup (int groupId, IList<View> views, Dimension dimension, int size)
         {
             if (views is null)
             {
                 return;
             }
+
             Aligner firstInGroup = null;
             List<int> dimensionsList = new ();
+
             List<View> viewsInGroup = views.Where (
                                                    v =>
                                                    {
@@ -564,15 +577,17 @@ public class Pos
                                                        }
 
                                                        return false;
-                                                   }).ToList ();
+                                                   })
+                                           .ToList ();
+
             if (viewsInGroup.Count == 0)
             {
                 return;
             }
 
-            foreach (var view in viewsInGroup)
+            foreach (View view in viewsInGroup)
             {
-                var posAlign = dimension == Dimension.Width ? view.X as PosAlign : view.Y as PosAlign;
+                PosAlign posAlign = dimension == Dimension.Width ? view.X as PosAlign : view.Y as PosAlign;
 
                 if (posAlign is { })
                 {
@@ -591,7 +606,7 @@ public class Pos
             }
 
             firstInGroup.ContainerSize = size;
-            var locations = firstInGroup.Align (dimensionsList.ToArray ());
+            int [] locations = firstInGroup.Align (dimensionsList.ToArray ());
 
             for (var index = 0; index < viewsInGroup.Count; index++)
             {
@@ -606,47 +621,35 @@ public class Pos
         }
 
         /// <summary>
-        /// Enables alignment of a set of views.
+        ///     Enables alignment of a set of views.
         /// </summary>
         /// <param name="alignment"></param>
         /// <param name="groupId">The unique identifier for the set of views to align according to <paramref name="alignment"/>.</param>
         public PosAlign (Alignment alignment, int groupId = 0)
         {
-            Aligner.PutSpaceBetweenItems = true;
+            Aligner.SpaceBetweenItems = true;
             Aligner.Alignment = alignment;
             _groupId = groupId;
             Aligner.PropertyChanged += Aligner_PropertyChanged;
         }
 
-        private void Aligner_PropertyChanged (object sender, System.ComponentModel.PropertyChangedEventArgs e)
-        {
-            _location = null;
-        }
+        private void Aligner_PropertyChanged (object sender, PropertyChangedEventArgs e) { _location = null; }
 
-        /// <inheritdoc />
+        /// <inheritdoc/>
         public override bool Equals (object other)
         {
             return other is PosAlign align && _groupId == align._groupId && _location == align._location && align.Aligner.Alignment == Aligner.Alignment;
         }
 
-        /// <inheritdoc />
-        public override int GetHashCode ()
-        {
-            return Aligner.GetHashCode () ^ _groupId.GetHashCode ();
-        }
+        /// <inheritdoc/>
+        public override int GetHashCode () { return Aligner.GetHashCode () ^ _groupId.GetHashCode (); }
 
-        /// <inheritdoc />
-        public override string ToString ()
-        {
-            return $"Align(groupId={_groupId}, alignment={Aligner.Alignment})";
-        }
+        /// <inheritdoc/>
+        public override string ToString () { return $"Align(groupId={_groupId}, alignment={Aligner.Alignment})"; }
 
-        internal override int Anchor (int width)
-        {
-            return _location ?? 0 - width;
-        }
+        internal override int Anchor (int width) { return _location ?? 0 - width; }
 
-        internal override int Calculate (int superviewDimension, Dim dim, View us, Dim.Dimension dimension)
+        internal override int Calculate (int superviewDimension, Dim dim, View us, Dimension dimension)
         {
             if (_location.HasValue && Aligner.ContainerSize == superviewDimension)
             {
@@ -667,8 +670,8 @@ public class Pos
 
             return 0;
         }
-
     }
+
     // Helper class to provide dynamic value by the execution of a function that returns an integer.
     internal class PosFunc (Func<int> n) : Pos
     {
@@ -679,28 +682,29 @@ public class Pos
         internal override int Anchor (int width) { return _function (); }
     }
 
+    // TODO: This should not be a nested enum. Extract it.
     /// <summary>
-    /// Describes which side of the view to use for the position.
+    ///     Describes which side of the view to use for the position.
     /// </summary>
     public enum Side
     {
         /// <summary>
-        /// The left (X) side of the view.
+        ///     The left (X) side of the view.
         /// </summary>
         Left = 0,
 
         /// <summary>
-        /// The top (Y) side of the view.
+        ///     The top (Y) side of the view.
         /// </summary>
         Top = 1,
 
         /// <summary>
-        /// The right (X + Width) side of the view.
+        ///     The right (X + Width) side of the view.
         /// </summary>
         Right = 2,
 
         /// <summary>
-        /// The bottom (Y + Height) side of the view.
+        ///     The bottom (Y + Height) side of the view.
         /// </summary>
         Bottom = 3
     }
@@ -744,14 +748,12 @@ public class Pos
         }
 
         /// <summary>
-        /// Diagnostics API to determine if this Pos object references other views.
+        ///     Diagnostics API to determine if this Pos object references other views.
         /// </summary>
         /// <returns></returns>
-        internal override bool ReferencesOtherViews ()
-        {
-            return true;
-        }
+        internal override bool ReferencesOtherViews () { return true; }
     }
+    #endregion Pos Types
 }
 
 /// <summary>
@@ -846,56 +848,54 @@ public class Dim
 
         /// <summary>
         ///     The dimensions will be computed based on the View's non-Text content.
-        /// <para>
-        ///     If <see cref="View.ContentSize"/> is explicitly set (is not <see langword="null"/>) then <see cref="View.ContentSize"/>
-        ///     will be used to determine the dimension.
-        /// </para>
-        /// <para>
-        ///     Otherwise, the Subview in <see cref="View.Subviews"/> with the largest corresponding position plus dimension
-        ///     will determine the dimension.
-        /// </para>
-        /// <para>
-        ///     The corresponding dimension of the view's <see cref="View.Text"/> will be ignored.
-        /// </para>
+        ///     <para>
+        ///         If <see cref="View.ContentSize"/> is explicitly set (is not <see langword="null"/>) then
+        ///         <see cref="View.ContentSize"/>
+        ///         will be used to determine the dimension.
+        ///     </para>
+        ///     <para>
+        ///         Otherwise, the Subview in <see cref="View.Subviews"/> with the largest corresponding position plus dimension
+        ///         will determine the dimension.
+        ///     </para>
+        ///     <para>
+        ///         The corresponding dimension of the view's <see cref="View.Text"/> will be ignored.
+        ///     </para>
         /// </summary>
         Content = 1,
 
         /// <summary>
-        /// <para>
-        ///     The corresponding dimension of the view's <see cref="View.Text"/>, formatted using the
-        ///     <see cref="View.TextFormatter"/> settings,
-        ///     will be used to determine the dimension.
-        /// </para>
-        /// <para>
-        ///     The corresponding dimensions of the <see cref="View.Subviews"/> will be ignored.
-        /// </para>
+        ///     <para>
+        ///         The corresponding dimension of the view's <see cref="View.Text"/>, formatted using the
+        ///         <see cref="View.TextFormatter"/> settings,
+        ///         will be used to determine the dimension.
+        ///     </para>
+        ///     <para>
+        ///         The corresponding dimensions of the <see cref="View.Subviews"/> will be ignored.
+        ///     </para>
         /// </summary>
         Text = 2
     }
 
-
     /// <summary>
-    /// 
     /// </summary>
     public enum Dimension
     {
         /// <summary>
-        /// No dimension specified.
+        ///     No dimension specified.
         /// </summary>
         None = 0,
 
         /// <summary>
-        /// The height dimension.
+        ///     The height dimension.
         /// </summary>
         Height = 1,
 
         /// <summary>
-        /// The width dimension.
+        ///     The width dimension.
         /// </summary>
         Width = 2
     }
 
-
     /// <summary>
     ///     Creates a <see cref="Dim"/> object that automatically sizes the view to fit all the view's SubViews and/or Text.
     /// </summary>
@@ -907,7 +907,7 @@ public class Dim
     /// <example>
     ///     This initializes a <see cref="View"/> with two SubViews. The view will be automatically sized to fit the two
     ///     SubViews.
-    /// <code>
+    ///     <code>
     /// var button = new Button () { Text = "Click Me!", X = 1, Y = 1, Width = 10, Height = 1 };
     /// var textField = new TextField { Text = "Type here", X = 1, Y = 2, Width = 20, Height = 1 };
     /// var view = new Window () { Title = "MyWindow", X = 0, Y = 0, Width = Dim.Auto (), Height = Dim.Auto () };
@@ -1060,7 +1060,8 @@ public class Dim
 
     /// <summary>
     ///     Calculates and returns the dimension of a <see cref="View"/> object. It takes into account the location of the
-    ///     <see cref="View"/>, it's SuperView's ContentSize, and whether it should automatically adjust its size based on its content.
+    ///     <see cref="View"/>, it's SuperView's ContentSize, and whether it should automatically adjust its size based on its
+    ///     content.
     /// </summary>
     /// <param name="location">
     ///     The starting point from where the size calculation begins. It could be the left edge for width calculation or the
@@ -1079,13 +1080,10 @@ public class Dim
     }
 
     /// <summary>
-    /// Diagnostics API to determine if this Dim object references other views.
+    ///     Diagnostics API to determine if this Dim object references other views.
     /// </summary>
     /// <returns></returns>
-    internal virtual bool ReferencesOtherViews ()
-    {
-        return false;
-    }
+    internal virtual bool ReferencesOtherViews () { return false; }
 
     internal class DimAbsolute (int n) : Dim
     {
@@ -1111,7 +1109,8 @@ public class Dim
     ///     </para>
     /// </remarks>
     /// <param name="style">
-    ///     Specifies how <see cref="Dim.DimAuto"/> will compute the dimension. The default is <see cref="Dim.DimAutoStyle.Auto"/>.
+    ///     Specifies how <see cref="Dim.DimAuto"/> will compute the dimension. The default is
+    ///     <see cref="Dim.DimAutoStyle.Auto"/>.
     /// </param>
     /// <param name="min">Specifies the minimum dimension that view will be automatically sized to.</param>
     /// <param name="max">Specifies the maximum dimension that view will be automatically sized to. NOT CURRENTLY SUPPORTED.</param>
@@ -1122,11 +1121,13 @@ public class Dim
         internal readonly DimAutoStyle _style = style;
         internal int _size;
 
-        /// <inheritdoc />
+        /// <inheritdoc/>
         public override bool Equals (object other) { return other is DimAuto auto && auto._min == _min && auto._max == _max && auto._style == _style; }
-        /// <inheritdoc />
+
+        /// <inheritdoc/>
         public override int GetHashCode () { return HashCode.Combine (base.GetHashCode (), _min, _max, _style); }
-        /// <inheritdoc />
+
+        /// <inheritdoc/>
         public override string ToString () { return $"Auto({_style},{_min},{_max})"; }
 
         internal override int Calculate (int location, int superviewContentSize, View us, Dimension dimension)
@@ -1148,7 +1149,7 @@ public class Dim
                 return superviewContentSize;
             }
 
-            if (_style.HasFlag (Dim.DimAutoStyle.Text))
+            if (_style.HasFlag (DimAutoStyle.Text))
             {
                 textSize = int.Max (autoMin, dimension == Dimension.Width ? us.TextFormatter.Size.Width : us.TextFormatter.Size.Height);
             }
@@ -1164,12 +1165,13 @@ public class Dim
                     // TODO: AnchorEnd needs work
                     // TODO: If _min > 0 we can SetRelativeLayout for the subviews?
                     subviewsSize = 0;
+
                     if (us.Subviews.Count > 0)
                     {
-                        for (int i = 0; i < us.Subviews.Count; i++)
+                        for (var i = 0; i < us.Subviews.Count; i++)
                         {
-                            var v = us.Subviews [i];
-                            bool isNotPosAnchorEnd = dimension == Dim.Dimension.Width ? v.X is not Pos.PosAnchorEnd : v.Y is not Pos.PosAnchorEnd;
+                            View v = us.Subviews [i];
+                            bool isNotPosAnchorEnd = dimension == Dimension.Width ? v.X is not Pos.PosAnchorEnd : v.Y is not Pos.PosAnchorEnd;
 
                             //if (!isNotPosAnchorEnd)
                             //{
@@ -1178,7 +1180,8 @@ public class Dim
 
                             if (isNotPosAnchorEnd)
                             {
-                                int size = dimension == Dim.Dimension.Width ? v.Frame.X + v.Frame.Width : v.Frame.Y + v.Frame.Height;
+                                int size = dimension == Dimension.Width ? v.Frame.X + v.Frame.Width : v.Frame.Y + v.Frame.Height;
+
                                 if (size > subviewsSize)
                                 {
                                     subviewsSize = size;
@@ -1186,7 +1189,6 @@ public class Dim
                             }
                         }
                     }
-
                 }
             }
 
@@ -1204,20 +1206,21 @@ public class Dim
             }
 
             max = int.Max (max, autoMin);
+
             return int.Min (max, _max?.Anchor (superviewContentSize) ?? superviewContentSize);
         }
 
         /// <summary>
-        /// Diagnostics API to determine if this Dim object references other views.
+        ///     Diagnostics API to determine if this Dim object references other views.
         /// </summary>
         /// <returns></returns>
         internal override bool ReferencesOtherViews ()
         {
             // BUGBUG: This is not correct. _contentSize may be null.
-            return _style.HasFlag (Dim.DimAutoStyle.Content);
+            return _style.HasFlag (DimAutoStyle.Content);
         }
-
     }
+
     internal class DimCombine (bool add, Dim left, Dim right) : Dim
     {
         internal bool _add = add;
@@ -1257,9 +1260,8 @@ public class Dim
             return newDimension;
         }
 
-
         /// <summary>
-        /// Diagnostics API to determine if this Dim object references other views.
+        ///     Diagnostics API to determine if this Dim object references other views.
         /// </summary>
         /// <returns></returns>
         internal override bool ReferencesOtherViews ()
@@ -1355,9 +1357,6 @@ public class Dim
             };
         }
 
-        internal override bool ReferencesOtherViews ()
-        {
-            return true;
-        }
+        internal override bool ReferencesOtherViews () { return true; }
     }
-}
+}

Terminal.Gui/Views/TileView.cs

@@ -417,6 +417,7 @@ public class TileView : View
     /// </summary>
     public bool SetSplitterPos (int idx, Pos value)
     {
+        // BUGBUG: PosAbsolute & PosFactor are internal API. TileView should not be using it and should do something different to get the value.
         if (!(value is Pos.PosAbsolute) && !(value is Pos.PosFactor))
         {
             throw new ArgumentException (
@@ -601,10 +602,12 @@ public class TileView : View
 
         TileViewLineView nextSplitter = visibleSplitterLines [i];
         Pos nextSplitterPos = Orientation == Orientation.Vertical ? nextSplitter.X : nextSplitter.Y;
+        // BUGBUG: Pos.Anchor is an internal API. TileView should not be using it and should do something different to get the value.
         int nextSplitterDistance = nextSplitterPos.Anchor (space);
 
         TileViewLineView lastSplitter = i >= 1 ? visibleSplitterLines [i - 1] : null;
         Pos lastSplitterPos = Orientation == Orientation.Vertical ? lastSplitter?.X : lastSplitter?.Y;
+        // BUGBUG: Pos.Anchor is an internal API. TileView should not be using it and should do something different to get the value.
         int lastSplitterDistance = lastSplitterPos?.Anchor (space) ?? 0;
 
         int distance = nextSplitterDistance - lastSplitterDistance;

UICatalog/Scenarios/PosAlign.cs

@@ -64,7 +64,7 @@ public sealed class PosAlign : Scenario
                                                          {
                                                              Aligner =
                                                              {
-                                                                 PutSpaceBetweenItems = _horizAligner.PutSpaceBetweenItems
+                                                                 SpaceBetweenItems = _horizAligner.SpaceBetweenItems
                                                              }
                                                          };
                                                          view.X = newJust;
@@ -83,13 +83,13 @@ public sealed class PosAlign : Scenario
 
         putSpaces.Toggled += (s, e) =>
                              {
-                                 _horizAligner.PutSpaceBetweenItems = e.NewValue is { } && e.NewValue.Value;
+                                 _horizAligner.SpaceBetweenItems = e.NewValue is { } && e.NewValue.Value;
 
                                  foreach (View view in appWindow.Subviews.Where (v => v.X is Pos.PosAlign))
                                  {
                                      if (view.X is Pos.PosAlign j)
                                      {
-                                         j.Aligner.PutSpaceBetweenItems = _horizAligner.PutSpaceBetweenItems;
+                                         j.Aligner.SpaceBetweenItems = _horizAligner.SpaceBetweenItems;
                                      }
                                  }
                              };
@@ -210,7 +210,7 @@ public sealed class PosAlign : Scenario
                                                          {
                                                              Aligner =
                                                              {
-                                                                 PutSpaceBetweenItems = _vertAligner.PutSpaceBetweenItems
+                                                                 SpaceBetweenItems = _vertAligner.SpaceBetweenItems
                                                              }
                                                          };
                                                          view.Y = newJust;
@@ -229,13 +229,13 @@ public sealed class PosAlign : Scenario
 
         putSpaces.Toggled += (s, e) =>
                              {
-                                 _vertAligner.PutSpaceBetweenItems = e.NewValue is { } && e.NewValue.Value;
+                                 _vertAligner.SpaceBetweenItems = e.NewValue is { } && e.NewValue.Value;
 
                                  foreach (View view in appWindow.Subviews.Where (v => v.Y is Pos.PosAlign))
                                  {
                                      if (view.Y is Pos.PosAlign j)
                                      {
-                                         j.Aligner.PutSpaceBetweenItems = _vertAligner.PutSpaceBetweenItems;
+                                         j.Aligner.SpaceBetweenItems = _vertAligner.SpaceBetweenItems;
                                      }
                                  }
                              };

UnitTests/Drawing/AlignerTests.cs

@@ -230,11 +230,11 @@ public class AlignerTests (ITestOutputHelper output)
     [InlineData (Alignment.FirstLeftRestRight, new [] { 10, 20, 30, 40, 50 }, 151, new [] { 0, 10, 30, 60, 101 })]
     [InlineData (Alignment.FirstLeftRestRight, new [] { 3, 3, 3 }, 21, new [] { 0, 14, 18 })]
     [InlineData (Alignment.FirstLeftRestRight, new [] { 3, 4, 5 }, 21, new [] { 0, 11, 16 })]
-    public void Alignment_PutSpaceBetweenItems (Alignment alignment, int [] sizes, int containerSize, int [] expected)
+    public void Alignment_SpaceBetweenItems (Alignment alignment, int [] sizes, int containerSize, int [] expected)
     {
         int [] positions = new Aligner
         {
-            PutSpaceBetweenItems = true,
+            SpaceBetweenItems = true,
             Alignment = alignment,
             ContainerSize = containerSize
         }.Align (sizes);
@@ -394,7 +394,7 @@ public class AlignerTests (ITestOutputHelper output)
     {
         int [] positions = new Aligner
         {
-            PutSpaceBetweenItems = false,
+            SpaceBetweenItems = false,
             Alignment = alignment,
             ContainerSize = containerSize
         }.Align (sizes);