From e01af595438fe22fb0f4057a0c0597df2ac8cee2 Mon Sep 17 00:00:00 2001
From: Tig <tig@users.noreply.github.com>
Date: Wed, 18 Sep 2024 12:57:49 -0600
Subject: [PATCH] Code cleanup/API docs

---
 Terminal.Gui/Application/ApplicationNavigation.cs | 10 ----------
 Terminal.Gui/View/Adornment/Border.cs             | 12 ++++++++++++
 Terminal.Gui/View/View.Drawing.cs                 |  6 +++++-
 Terminal.Gui/View/View.Layout.cs                  |  2 ++
 4 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/Terminal.Gui/Application/ApplicationNavigation.cs b/Terminal.Gui/Application/ApplicationNavigation.cs
index cc1df9a7e..2523709d0 100644
--- a/Terminal.Gui/Application/ApplicationNavigation.cs
+++ b/Terminal.Gui/Application/ApplicationNavigation.cs
@@ -62,11 +62,6 @@ public class ApplicationNavigation
             }
         }
 
-        //if (start.Border is { })
-        //{
-        //    return IsInHierarchy (start.Border, view);
-        //}
-
         return false;
     }
 
@@ -85,11 +80,6 @@ public class ApplicationNavigation
 
         _focused = value;
 
-        //if (_focused is { } && Application.PositionCursor ())
-        //{
-        //    Application.Driver?.UpdateCursor ();
-        //}
-
         FocusedChanged?.Invoke (null, EventArgs.Empty);
     }
 
diff --git a/Terminal.Gui/View/Adornment/Border.cs b/Terminal.Gui/View/Adornment/Border.cs
index 181526158..783a74f5c 100644
--- a/Terminal.Gui/View/Adornment/Border.cs
+++ b/Terminal.Gui/View/Adornment/Border.cs
@@ -317,6 +317,9 @@ public class Border : Adornment
 
                 SetHighlight (HighlightStyle);
 
+                // Arrange Mode -
+                // TODO: This code can be refactored to be more readable and maintainable.
+
                 // If not resizable, but movable: Drag anywhere is move
                 // If resizable and movable: Drag on top is move, other 3 sides are size
                 // If not movable, but resizable: Drag on any side sizes.
@@ -468,6 +471,7 @@ public class Border : Adornment
                 int minHeight = Thickness.Vertical + Parent!.Margin.Thickness.Bottom;
                 int minWidth = Thickness.Horizontal + Parent!.Margin.Thickness.Right;
 
+                // TODO: This code can be refactored to be more readable and maintainable.
                 switch (_arranging)
                 {
                     case ViewArrangement.Movable:
@@ -989,6 +993,8 @@ public class Border : Adornment
 
         Application.MouseEvent += ApplicationOnMouseEvent;
 
+        // TODO: This code can be refactored to be more readable and maintainable.
+
         // Create buttons for resizing and moving
         if (Parent!.Arrangement.HasFlag (ViewArrangement.Movable))
         {
@@ -1222,6 +1228,7 @@ public class Border : Adornment
             if (arrangement == ViewArrangement.Fixed)
             {
                 // Keyboard mode - enable nav
+                // TODO: Keyboard mode only supports sizing from bottom/right.
                 _arranging = (ViewArrangement)(Focused?.Data ?? ViewArrangement.Fixed);
             }
 
@@ -1344,6 +1351,11 @@ public class Border : Adornment
                     Command.Tab,
                     () =>
                     {
+                        // BUGBUG: If an arrangable view has only arrangable subviews, it's not possible to activate
+                        // BUGBUG: ArrangeMode with keyboard for the superview.
+                        // BUGBUG: AdvanceFocus should be wise to this and when in ArrangeMode, should move across
+                        // BUGBUG: the view hierachy.
+
                         AdvanceFocus (NavigationDirection.Forward, TabBehavior.TabStop);
                         _arranging = (ViewArrangement)(Focused?.Data ?? ViewArrangement.Fixed);
 
diff --git a/Terminal.Gui/View/View.Drawing.cs b/Terminal.Gui/View/View.Drawing.cs
index 2dcd62824..b5980bd9b 100644
--- a/Terminal.Gui/View/View.Drawing.cs
+++ b/Terminal.Gui/View/View.Drawing.cs
@@ -187,11 +187,15 @@ public partial class View // Drawing APIs
     }
 
     /// <summary>
-    ///     Draws the view. Causes the following virtual methods to be called (along with their related events):
+    ///     Draws the view if it needs to be drawn. Causes the following virtual methods to be called (along with their related events):
     ///     <see cref="OnDrawContent"/>, <see cref="OnDrawContentComplete"/>.
     /// </summary>
     /// <remarks>
     ///     <para>
+    ///         The view will only be drawn if it is visible, and has any of <see cref="NeedsDisplay"/>, <see cref="SubViewNeedsDisplay"/>,
+    ///         or <see cref="LayoutNeeded"/> set.
+    ///     </para>
+    ///     <para>
     ///         Always use <see cref="Viewport"/> (view-relative) when calling <see cref="OnDrawContent(Rectangle)"/>, NOT
     ///         <see cref="Frame"/> (superview-relative).
     ///     </para>
diff --git a/Terminal.Gui/View/View.Layout.cs b/Terminal.Gui/View/View.Layout.cs
index cd0225819..49491dee4 100644
--- a/Terminal.Gui/View/View.Layout.cs
+++ b/Terminal.Gui/View/View.Layout.cs
@@ -771,6 +771,8 @@ public partial class View // Layout APIs
 
         SetNeedsLayout ();
 
+        // TODO: This ensures overlapped views are drawn correctly. However, this is inefficient.
+        // TODO: The correct fix is to implement non-rectangular clip regions: https://github.com/gui-cs/Terminal.Gui/issues/3413
         if (Arrangement.HasFlag (ViewArrangement.Overlapped))
         {
             foreach (Toplevel v in Application.TopLevels)