Added API docs indicating low-level nature of pos/dom classes

Terminal.Gui/View/Layout/Dim.cs

@@ -330,6 +330,12 @@ public class Dim
 /// <summary>
 ///     Represents a dimension that is a fixed size.
 /// </summary>
+/// <remarks>
+///     <para>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Dim"/> class to create <see cref="Dim"/> objects instead.
+///     </para>
+/// </remarks>
 /// <param name="size"></param>
 public class DimAbsolute (int size) : Dim
 {
@@ -363,6 +369,10 @@ public class DimAbsolute (int size) : Dim
 ///     <para>
 ///         See <see cref="DimAutoStyle"/>.
 ///     </para>
+///     <para>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Dim"/> class to create <see cref="Dim"/> objects instead.
+///     </para>
 /// </remarks>
 /// <param name="style">
 ///     Specifies how <see cref="DimAuto"/> will compute the dimension. The default is <see cref="DimAutoStyle.Auto"/>.
@@ -497,6 +507,10 @@ public class DimAuto (DimAutoStyle style, Dim minimumContentDim, Dim maximumCont
 ///     Indicates whether the two dimensions are added or subtracted. If <see langword="true"/>, the dimensions are added,
 ///     otherwise they are subtracted.
 /// </param>
+/// <remarks>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Dim"/> class to create <see cref="Dim"/> objects instead.
+/// </remarks>
 /// <param name="left">The left dimension.</param>
 /// <param name="right">The right dimension.</param>
 public class DimCombine (bool add, Dim left, Dim right) : Dim
@@ -574,6 +588,10 @@ public class DimCombine (bool add, Dim left, Dim right) : Dim
 /// <summary>
 ///     Represents a dimension that is a percentage of the width or height of the SuperView.
 /// </summary>
+/// <remarks>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Dim"/> class to create <see cref="Dim"/> objects instead.
+/// </remarks>
 /// <param name="percent">The percentage.</param>
 /// <param name="usePosition">
 ///     If <see langword="true"/> the dimension is computed using the View's position (<see cref="View.X"/> or
@@ -614,6 +632,10 @@ public class DimPercent (float percent, bool usePosition = false) : Dim
 /// <summary>
 ///     Represents a dimension that fills the dimension, leaving the specified margin.
 /// </summary>
+/// <remarks>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Dim"/> class to create <see cref="Dim"/> objects instead.
+/// </remarks>
 /// <param name="margin">The margin to not fill.</param>
 public class DimFill (int margin) : Dim
 {
@@ -637,6 +659,10 @@ public class DimFill (int margin) : Dim
 /// <summary>
 ///     Represents a function <see cref="Dim"/> object that computes the dimension by executing the provided function.
 /// </summary>
+/// <remarks>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Dim"/> class to create <see cref="Dim"/> objects instead.
+/// </remarks>
 /// <param name="dim"></param>
 public class DimFunc (Func<int> dim) : Dim
 {
@@ -660,6 +686,10 @@ public class DimFunc (Func<int> dim) : Dim
 /// <summary>
 ///     Represents a dimension that tracks the Height or Width of the specified View.
 /// </summary>
+/// <remarks>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Dim"/> class to create <see cref="Dim"/> objects instead.
+/// </remarks>
 public class DimView : Dim
 {
     /// <summary>

Terminal.Gui/View/Layout/Pos.cs

@@ -382,6 +382,12 @@ public class Pos
 /// <summary>
 ///    Represents an absolute position in the layout. This is used to specify a fixed position in the layout.
 /// </summary>
+/// <remarks>
+///     <para>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Pos"/> class to create <see cref="Pos"/> objects instead.
+///     </para>
+/// </remarks>
 /// <param name="position"></param>
 public class PosAbsolute (int position) : Pos
 {
@@ -405,6 +411,12 @@ public class PosAbsolute (int position) : Pos
 /// <summary>
 ///     Represents a position anchored to the end (right side or bottom).
 /// </summary>
+/// <remarks>
+///     <para>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Pos"/> class to create <see cref="Pos"/> objects instead.
+///     </para>
+/// </remarks>
 public class PosAnchorEnd : Pos
 {
     /// <summary>
@@ -483,6 +495,12 @@ public class PosCenter : Pos
 /// <summary>
 ///    Represents a position that is a combination of two other positions.
 /// </summary>
+/// <remarks>
+///     <para>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Pos"/> class to create <see cref="Pos"/> objects instead.
+///     </para>
+/// </remarks>
 /// <param name="add">Indicates whether the two positions are added or subtracted. If <see langword="true"/>, the positions are added, otherwise they are subtracted.</param>
 /// <param name="left">The left position.</param>
 /// <param name="right">The right position.</param>
@@ -552,6 +570,12 @@ public class PosCombine (bool add, Pos left, Pos right) : Pos
 /// <summary>
 ///     Represents a position that is a percentage of the width or height of the SuperView.
 /// </summary>
+/// <remarks>
+///     <para>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Pos"/> class to create <see cref="Pos"/> objects instead.
+///     </para>
+/// </remarks>
 /// <param name="percent"></param>
 public class PosPercent (float percent) : Pos
 {
@@ -575,6 +599,12 @@ public class PosPercent (float percent) : Pos
 /// <summary>
 ///    Represents a position that is computed by executing a function that returns an integer position.
 /// </summary>
+/// <remarks>
+///     <para>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Pos"/> class to create <see cref="Pos"/> objects instead.
+///     </para>
+/// </remarks>
 /// <param name="pos">The position.</param>
 public class PosFunc (Func<int> pos) : Pos
 {
@@ -598,6 +628,12 @@ public class PosFunc (Func<int> pos) : Pos
 /// <summary>
 ///     Represents a position that is anchored to the side of another view.
 /// </summary>
+/// <remarks>
+///     <para>
+///     This is a low-level API that is typically used internally by the layout system. Use the various static
+///     methods on the <see cref="Pos"/> class to create <see cref="Pos"/> objects instead.
+///     </para>
+/// </remarks>
 /// <param name="view">The View the position is anchored to.</param>
 /// <param name="side">The side of the View the position is anchored to.</param>
 public class PosView (View view, Side side) : Pos
@@ -618,11 +654,7 @@ public class PosView (View view, Side side) : Pos
     /// <inheritdoc />
     public override int GetHashCode () { return Target.GetHashCode (); }
 
-    /// <summary>
-    /// 
-    /// </summary>
-    /// <returns></returns>
-    /// <exception cref="NullReferenceException"></exception>
+    /// <inheritdoc />
     public override string ToString ()
     {
         string sideString = Side switch