From ce6beb8851aa0cdb1c1601a69b56a277cfcfe5f6 Mon Sep 17 00:00:00 2001
From: Dan Walmsley <dan@walms.co.uk>
Date: Tue, 23 Jun 2020 17:59:06 -0300
Subject: [PATCH] add some documentation.

---
 src/Avalonia.Controls/Platform/IWindowImpl.cs | 30 +++++++++++++++++++
 src/Avalonia.Native/WindowImpl.cs             | 13 ++++----
 src/Windows/Avalonia.Win32/WindowImpl.cs      | 22 ++++++++------
 3 files changed, 49 insertions(+), 16 deletions(-)

diff --git a/src/Avalonia.Controls/Platform/IWindowImpl.cs b/src/Avalonia.Controls/Platform/IWindowImpl.cs
index 55fe8c328b..43647dc7d0 100644
--- a/src/Avalonia.Controls/Platform/IWindowImpl.cs
+++ b/src/Avalonia.Controls/Platform/IWindowImpl.cs
@@ -95,20 +95,50 @@ namespace Avalonia.Platform
         /// 
         void SetMinMaxSize(Size minSize, Size maxSize);
 
+        /// <summary>
+        /// Sets if the ClientArea is extended into the non-client area.
+        /// </summary>
+        /// <param name="extendIntoClientAreaHint">true to enable, false to disable</param>
         void SetExtendClientAreaToDecorationsHint(bool extendIntoClientAreaHint);
 
+        /// <summary>
+        /// Gets a value to indicate if the platform was able to extend client area to non-client area.
+        /// </summary>
         bool IsClientAreaExtendedToDecorations { get; }
 
+        /// <summary>
+        /// Sets hints that configure how the client area extends. 
+        /// </summary>
+        /// <param name="hints"></param>
         void SetExtendClientAreaChromeHints(ExtendClientAreaChromeHints hints);
 
+        /// <summary>
+        /// Sets how big the non-client titlebar area should be.
+        /// </summary>
+        /// <param name="titleBarHeight">-1 for platform default, otherwise the height in DIPs.</param>
         void SetExtendClientAreaTitleBarHeightHint(double titleBarHeight);
 
+        /// <summary>
+        /// Gets or Sets an action that is called whenever one of the extend client area properties changed.
+        /// </summary>
         Action<bool> ExtendClientAreaToDecorationsChanged { get; set; }
 
+        /// <summary>
+        /// Gets a flag that indicates if Managed decorations i.e. caption buttons are required.
+        /// This property is used when <see cref="IsClientAreaExtendedToDecorations"/> is set.
+        /// </summary>
         bool NeedsManagedDecorations { get; }
         
+        /// <summary>
+        /// Gets a thickness that describes the amount each side of the non-client area extends into the client area.
+        /// It includes the titlebar.
+        /// </summary>
         Thickness ExtendedMargins { get; }
 
+        /// <summary>
+        /// Gets a thickness that describes the margin around the window that is offscreen.
+        /// This may happen when a window is maximized and <see cref="IsClientAreaExtendedToDecorations"/> is set.
+        /// </summary>
         Thickness OffScreenMargin { get; } 
     }
 }
diff --git a/src/Avalonia.Native/WindowImpl.cs b/src/Avalonia.Native/WindowImpl.cs
index ce312b30d2..ef2bd32bfc 100644
--- a/src/Avalonia.Native/WindowImpl.cs
+++ b/src/Avalonia.Native/WindowImpl.cs
@@ -137,7 +137,7 @@ namespace Avalonia.Native
 
             return false;
         }
-
+        
         private void InvalidateExtendedMargins ()
         {
             if(WindowState ==  WindowState.FullScreen)
@@ -152,6 +152,7 @@ namespace Avalonia.Native
             ExtendClientAreaToDecorationsChanged?.Invoke(_isExtended);
         }
 
+        /// <inheritdoc/>
         public void SetExtendClientAreaToDecorationsHint(bool extendIntoClientAreaHint)
         {
             _isExtended = extendIntoClientAreaHint;
@@ -161,16 +162,13 @@ namespace Avalonia.Native
             InvalidateExtendedMargins();
         }
 
+        /// <inheritdoc/>
         public void SetExtendClientAreaChromeHints(ExtendClientAreaChromeHints hints)
-        {
-            if(hints.HasFlag(ExtendClientAreaChromeHints.PreferSystemChromeButtons))
-            {
-                hints |= ExtendClientAreaChromeHints.SystemChromeButtons;
-            }
-            
+        {   
             _native.SetExtendClientAreaHints ((AvnExtendClientAreaChromeHints)hints);
         }
 
+        /// <inheritdoc/>
         public void SetExtendClientAreaTitleBarHeightHint(double titleBarHeight)
         {
             _extendTitleBarHeight = titleBarHeight;
@@ -181,6 +179,7 @@ namespace Avalonia.Native
             ExtendClientAreaToDecorationsChanged?.Invoke(_isExtended);
         }
 
+        /// <inheritdoc/>
         public bool NeedsManagedDecorations => false;
 
         public void ShowTaskbarIcon(bool value)
diff --git a/src/Windows/Avalonia.Win32/WindowImpl.cs b/src/Windows/Avalonia.Win32/WindowImpl.cs
index 250b0cf029..6025f96d22 100644
--- a/src/Windows/Avalonia.Win32/WindowImpl.cs
+++ b/src/Windows/Avalonia.Win32/WindowImpl.cs
@@ -45,7 +45,8 @@ namespace Avalonia.Win32
         private bool _isClientAreaExtended;
         private Thickness _extendedMargins;
         private Thickness _offScreenMargin;
- 
+        private double _extendTitleBarHint = -1;
+
 #if USE_MANAGED_DRAG
         private readonly ManagedWindowResizeDragHelper _managedDrag;
 #endif
@@ -73,8 +74,8 @@ namespace Avalonia.Win32
         private Size _minSize;
         private Size _maxSize;
         private POINT _maxTrackSize;
-        private WindowImpl _parent;
-        private bool _extendClientAreaToDecorationsHint;
+        private WindowImpl _parent;        
+        private ExtendClientAreaChromeHints _extendChromeHints = ExtendClientAreaChromeHints.Default;
 
         public WindowImpl()
         {
@@ -1036,9 +1037,7 @@ namespace Avalonia.Win32
             _isClientAreaExtended = hint;
             
             ExtendClientArea();            
-        }
-
-        private ExtendClientAreaChromeHints _extendChromeHints = ExtendClientAreaChromeHints.Default;
+        }        
 
         public void SetExtendClientAreaChromeHints(ExtendClientAreaChromeHints hints)
         {
@@ -1046,8 +1045,8 @@ namespace Avalonia.Win32
 
             ExtendClientArea();
         }
-
-        private double _extendTitleBarHint = -1;
+        
+        /// <inheritdoc/>
         public void SetExtendClientAreaTitleBarHeightHint(double titleBarHeight)
         {
             _extendTitleBarHint = titleBarHeight;
@@ -1055,14 +1054,19 @@ namespace Avalonia.Win32
             ExtendClientArea();
         }
 
+        /// <inheritdoc/>
         public bool IsClientAreaExtendedToDecorations => _isClientAreaExtended;
 
+        /// <inheritdoc/>
         public Action<bool> ExtendClientAreaToDecorationsChanged { get; set; }
-
+        
+        /// <inheritdoc/>
         public bool NeedsManagedDecorations => _isClientAreaExtended && _extendChromeHints.HasFlag(ExtendClientAreaChromeHints.PreferSystemChromeButtons);
 
+        /// <inheritdoc/>
         public Thickness ExtendedMargins => _extendedMargins;
 
+        /// <inheritdoc/>
         public Thickness OffScreenMargin => _offScreenMargin;
 
         private struct SavedWindowInfo