API doc improvements

Terminal.Gui/View/Layout/PosDim.cs

@@ -1,4 +1,6 @@
-namespace Terminal.Gui;
+using static Terminal.Gui.Dialog;
+
+namespace Terminal.Gui;
 
 /// <summary>
 ///     Describes the position of a <see cref="View"/> which can be an absolute value, a percentage, centered, or
@@ -169,14 +171,6 @@ public class Pos
     /// <param name="n">The value to convert to the <see cref="Pos"/>.</param>
     public static Pos At (int n) { return new PosAbsolute (n); }
 
-    /// <summary>
-    ///     Creates a <see cref="Pos"/> object that tracks the Bottom (Y+Height) coordinate of the specified
-    ///     <see cref="View"/>
-    /// </summary>
-    /// <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) { return new PosView (view, Side.Bottom); }
-
     /// <summary>Creates a <see cref="Pos"/> object that can be used to center the <see cref="View"/>.</summary>
     /// <returns>The center Pos.</returns>
     /// <example>
@@ -213,11 +207,6 @@ public class Pos
     /// <returns>A hash code for the current object.</returns>
     public override int GetHashCode () { return Anchor (0).GetHashCode (); }
 
-    /// <summary>Creates a <see cref="Pos"/> object that tracks the Left (X) position of the specified <see cref="View"/>.</summary>
-    /// <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) { return new PosView (view, Side.X); }
-
     /// <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>
@@ -293,28 +282,41 @@ public class Pos
         return new PosFactor (percent / 100);
     }
 
-    /// <summary>
-    ///     Creates a <see cref="Pos"/> object that tracks the Right (X+Width) coordinate of the specified
-    ///     <see cref="View"/>.
-    /// </summary>
+    /// <summary>Creates a <see cref="Pos"/> object that tracks the Top (Y) position of the specified <see cref="View"/>.</summary>
     /// <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) { return new PosView (view, Side.Right); }
+    public static Pos Top (View view) { return new PosView (view, Side.Top); }
 
     /// <summary>Creates a <see cref="Pos"/> object that tracks the Top (Y) position of the specified <see cref="View"/>.</summary>
     /// <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) { return new PosView (view, Side.Y); }
+    public static Pos Y (View view) { return new PosView (view, Side.Top); }
 
     /// <summary>Creates a <see cref="Pos"/> object that tracks the Left (X) position of the specified <see cref="View"/>.</summary>
     /// <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) { return new PosView (view, Side.X); }
+    public static Pos Left (View view) { return new PosView (view, Side.Left); }
 
-    /// <summary>Creates a <see cref="Pos"/> object that tracks the Top (Y) position of the specified <see cref="View"/>.</summary>
+    /// <summary>Creates a <see cref="Pos"/> object that tracks the Left (X) position of the specified <see cref="View"/>.</summary>
     /// <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) { return new PosView (view, Side.Y); }
+    public static Pos X (View view) { return new PosView (view, Side.Left); }
+
+    /// <summary>
+    ///     Creates a <see cref="Pos"/> object that tracks the Bottom (Y+Height) coordinate of the specified
+    ///     <see cref="View"/>
+    /// </summary>
+    /// <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) { return new PosView (view, Side.Bottom); }
+
+    /// <summary>
+    ///     Creates a <see cref="Pos"/> object that tracks the Right (X+Width) coordinate of the specified
+    ///     <see cref="View"/>.
+    /// </summary>
+    /// <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) { return new PosView (view, Side.Right); }
 
     /// <summary>
     ///     Gets a position that is anchored to a certain point in the layout. This method is typically used
@@ -460,11 +462,29 @@ public class Pos
         internal override int Anchor (int width) { return _function (); }
     }
 
-    internal enum Side
+    /// <summary>
+    /// Describes which side of the view to use for the position.
+    /// </summary>
+    public enum Side
     {
-        X = 0,
-        Y = 1,
+        /// <summary>
+        /// The left (X) side of the view.
+        /// </summary>
+        Left = 0,
+
+        /// <summary>
+        /// The top (Y) side of the view.
+        /// </summary>
+        Top = 1,
+
+        /// <summary>
+        /// The right (X + Width) side of the view.
+        /// </summary>
         Right = 2,
+
+        /// <summary>
+        /// The bottom (Y + Height) side of the view.
+        /// </summary>
         Bottom = 3
     }
 
@@ -478,13 +498,13 @@ public class Pos
         public override string ToString ()
         {
             string sideString = side switch
-                                {
-                                    Side.X => "x",
-                                    Side.Y => "y",
-                                    Side.Right => "right",
-                                    Side.Bottom => "bottom",
-                                    _ => "unknown"
-                                };
+            {
+                Side.Left => "left",
+                Side.Top => "top",
+                Side.Right => "right",
+                Side.Bottom => "bottom",
+                _ => "unknown"
+            };
 
             if (Target == null)
             {
@@ -497,13 +517,13 @@ public class Pos
         internal override int Anchor (int width)
         {
             return side switch
-                   {
-                       Side.X => Target.Frame.X,
-                       Side.Y => Target.Frame.Y,
-                       Side.Right => Target.Frame.Right,
-                       Side.Bottom => Target.Frame.Bottom,
-                       _ => 0
-                   };
+            {
+                Side.Left => Target.Frame.X,
+                Side.Top => Target.Frame.Y,
+                Side.Right => Target.Frame.Right,
+                Side.Bottom => Target.Frame.Bottom,
+                _ => 0
+            };
         }
     }
 }
@@ -608,7 +628,7 @@ public class Dim
     /// <summary>Creates a <see cref="Dim"/> object that tracks the Height of the specified <see cref="View"/>.</summary>
     /// <returns>The height <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) { return new DimView (view, Side.Height); }
+    public static Dim Height (View view) { return new DimView (view, Dimension.Height); }
 
     /// <summary>Adds a <see cref="Dim"/> to a <see cref="Dim"/>, yielding a new <see cref="Dim"/>.</summary>
     /// <param name="left">The first <see cref="Dim"/> to add.</param>
@@ -691,7 +711,7 @@ public class Dim
     /// <summary>Creates a <see cref="Dim"/> object that tracks the Width of the specified <see cref="View"/>.</summary>
     /// <returns>The width <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) { return new DimView (view, Side.Width); }
+    public static Dim Width (View view) { return new DimView (view, Dimension.Width); }
 
     /// <summary>
     ///     Gets a dimension that is anchored to a certain point in the layout.
@@ -822,17 +842,27 @@ public class Dim
         internal override int Anchor (int width) { return _function (); }
     }
 
-    internal enum Side
+    /// <summary>
+    /// 
+    /// </summary>
+    public enum Dimension
     {
+        /// <summary>
+        /// The height dimension.
+        /// </summary>
         Height = 0,
+
+        /// <summary>
+        /// The width dimension.
+        /// </summary>
         Width = 1
     }
 
     internal class DimView : Dim
     {
-        private readonly Side _side;
+        private readonly Dimension _side;
 
-        internal DimView (View view, Side side)
+        internal DimView (View view, Dimension side)
         {
             Target = view;
             _side = side;
@@ -850,11 +880,11 @@ public class Dim
             }
 
             string sideString = _side switch
-                                {
-                                    Side.Height => "Height",
-                                    Side.Width => "Width",
-                                    _ => "unknown"
-                                };
+            {
+                Dimension.Height => "Height",
+                Dimension.Width => "Width",
+                _ => "unknown"
+            };
 
             return $"View({sideString},{Target})";
         }
@@ -862,11 +892,11 @@ public class Dim
         internal override int Anchor (int width)
         {
             return _side switch
-                   {
-                       Side.Height => Target.Frame.Height,
-                       Side.Width => Target.Frame.Width,
-                       _ => 0
-                   };
+            {
+                Dimension.Height => Target.Frame.Height,
+                Dimension.Width => Target.Frame.Width,
+                _ => 0
+            };
         }
     }
 }

UnitTests/View/Layout/DimTests.cs

@@ -70,7 +70,7 @@ public class DimTests
     public void DimView_GetDimension_ReturnsCorrectValue ()
     {
         var view = new View { Width = 10 };
-        var dim = new DimView (view, Side.Width);
+        var dim = new DimView (view, Dimension.Width);
         var result = dim.Calculate (0, 100, 50, false);
         Assert.Equal (10, result);
     }
@@ -561,9 +561,9 @@ public class DimTests
         Assert.Equal (20, dimCombine.Anchor (100));
 
         var view = new View { Frame = new Rectangle (20, 10, 20, 1) };
-        var dimViewHeight = new Dim.DimView (view, Side.Height);
+        var dimViewHeight = new Dim.DimView (view, Dimension.Height);
         Assert.Equal (1, dimViewHeight.Anchor (0));
-        var dimViewWidth = new Dim.DimView (view, Side.Width);
+        var dimViewWidth = new Dim.DimView (view, Dimension.Width);
         Assert.Equal (20, dimViewWidth.Anchor (0));
 
         view.Dispose ();

UnitTests/View/Layout/PosTests.cs

@@ -101,28 +101,28 @@ public class PosTests (ITestOutputHelper output)
         Pos pos = Pos.Left (v);
 
         Assert.Equal (
-                      $"View(side=x,target=View(V){v.Frame})",
+                      $"View(side=left,target=View(V){v.Frame})",
                       pos.ToString ()
                      );
 
         pos = Pos.X (v);
 
         Assert.Equal (
-                      $"View(side=x,target=View(V){v.Frame})",
+                      $"View(side=left,target=View(V){v.Frame})",
                       pos.ToString ()
                      );
 
         pos = Pos.Top (v);
 
         Assert.Equal (
-                      $"View(side=y,target=View(V){v.Frame})",
+                      $"View(side=top,target=View(V){v.Frame})",
                       pos.ToString ()
                      );
 
         pos = Pos.Y (v);
 
         Assert.Equal (
-                      $"View(side=y,target=View(V){v.Frame})",
+                      $"View(side=top,target=View(V){v.Frame})",
                       pos.ToString ()
                      );
 
@@ -197,9 +197,9 @@ public class PosTests (ITestOutputHelper output)
         Assert.Equal (20, posCombine.Anchor (100));
 
         var view = new View { Frame = new (20, 10, 20, 1) };
-        var posViewX = new Pos.PosView (view, Pos.Side.X);
+        var posViewX = new Pos.PosView (view, Pos.Side.Left);
         Assert.Equal (20, posViewX.Anchor (0));
-        var posViewY = new Pos.PosView (view, Pos.Side.Y);
+        var posViewY = new Pos.PosView (view, Pos.Side.Top);
         Assert.Equal (10, posViewY.Anchor (0));
         var posRight = new Pos.PosView (view, Pos.Side.Right);
         Assert.Equal (40, posRight.Anchor (0));
@@ -617,7 +617,7 @@ public class PosTests (ITestOutputHelper output)
         Pos pos;
 
         // Pos.Left
-        side = "x";
+        side = "left";
         testInt = 0;
         testRect = Rectangle.Empty;
         pos = Pos.Left (new ());
@@ -659,7 +659,7 @@ public class PosTests (ITestOutputHelper output)
                      );
 
         // Pos.X
-        side = "x";
+        side = "left";
         testInt = 0;
         testRect = Rectangle.Empty;
         pos = Pos.X (new ());
@@ -701,7 +701,7 @@ public class PosTests (ITestOutputHelper output)
                      );
 
         // Pos.Top
-        side = "y";
+        side = "top";
         testInt = 0;
         testRect = Rectangle.Empty;
         pos = Pos.Top (new ());
@@ -743,7 +743,7 @@ public class PosTests (ITestOutputHelper output)
                      );
 
         // Pos.Y
-        side = "y";
+        side = "top";
         testInt = 0;
         testRect = Rectangle.Empty;
         pos = Pos.Y (new ());