From cef5ffed901ef5a6bdfe3f13cba618163dca5da8 Mon Sep 17 00:00:00 2001
From: Steven Kirk <grokys@github.com>
Date: Thu, 10 Nov 2016 01:46:01 +0100
Subject: [PATCH] Docs and tweaking.

---
 src/Avalonia.Visuals/Avalonia.Visuals.csproj  |  2 +-
 .../Rendering/SceneGraph/GeometryNode.cs      |  2 +-
 .../Rendering/SceneGraph/IDrawNode.cs         | 12 -----
 .../Rendering/SceneGraph/IGeometryNode.cs     | 24 +++++++++
 .../Rendering/SceneGraph/ISceneNode.cs        |  7 +++
 .../Rendering/SceneGraph/IVisualNode.cs       | 39 +++++++++++++++
 .../Rendering/SceneGraph/ImageNode.cs         |  2 +-
 .../Rendering/SceneGraph/LineNode.cs          |  2 +-
 .../Rendering/SceneGraph/RectangleNode.cs     |  2 +-
 .../Rendering/SceneGraph/TextNode.cs          |  2 +-
 .../Rendering/SceneGraph/VisualNode.cs        | 49 ++++++++++++++++++-
 11 files changed, 123 insertions(+), 20 deletions(-)
 delete mode 100644 src/Avalonia.Visuals/Rendering/SceneGraph/IDrawNode.cs
 create mode 100644 src/Avalonia.Visuals/Rendering/SceneGraph/IGeometryNode.cs

diff --git a/src/Avalonia.Visuals/Avalonia.Visuals.csproj b/src/Avalonia.Visuals/Avalonia.Visuals.csproj
index bc41f646d9..83c65c34a5 100644
--- a/src/Avalonia.Visuals/Avalonia.Visuals.csproj
+++ b/src/Avalonia.Visuals/Avalonia.Visuals.csproj
@@ -115,7 +115,7 @@
     <Compile Include="Rendering\DefaultRenderLoop.cs" />
     <Compile Include="Rendering\SceneGraph\DeferredDrawingContextImpl.cs" />
     <Compile Include="Rendering\SceneGraph\GeometryNode.cs" />
-    <Compile Include="Rendering\SceneGraph\IDrawNode.cs" />
+    <Compile Include="Rendering\SceneGraph\IGeometryNode.cs" />
     <Compile Include="Rendering\SceneGraph\ImageNode.cs" />
     <Compile Include="Rendering\SceneGraph\ISceneNode.cs" />
     <Compile Include="Rendering\SceneGraph\IVisualNode.cs" />
diff --git a/src/Avalonia.Visuals/Rendering/SceneGraph/GeometryNode.cs b/src/Avalonia.Visuals/Rendering/SceneGraph/GeometryNode.cs
index fa40eb04ed..ce7e6f9b1d 100644
--- a/src/Avalonia.Visuals/Rendering/SceneGraph/GeometryNode.cs
+++ b/src/Avalonia.Visuals/Rendering/SceneGraph/GeometryNode.cs
@@ -7,7 +7,7 @@ using Avalonia.Platform;
 
 namespace Avalonia.Rendering.SceneGraph
 {
-    public class GeometryNode : IDrawNode
+    public class GeometryNode : IGeometryNode
     {
         public GeometryNode(Matrix transform, IBrush brush, Pen pen, IGeometryImpl geometry)
         {
diff --git a/src/Avalonia.Visuals/Rendering/SceneGraph/IDrawNode.cs b/src/Avalonia.Visuals/Rendering/SceneGraph/IDrawNode.cs
deleted file mode 100644
index 0b4507bccb..0000000000
--- a/src/Avalonia.Visuals/Rendering/SceneGraph/IDrawNode.cs
+++ /dev/null
@@ -1,12 +0,0 @@
-// Copyright (c) The Avalonia Project. All rights reserved.
-// Licensed under the MIT license. See licence.md file in the project root for full license information.
-
-using System;
-
-namespace Avalonia.Rendering.SceneGraph
-{
-    public interface IDrawNode : ISceneNode
-    {
-        bool HitTest(Point p);
-    }
-}
diff --git a/src/Avalonia.Visuals/Rendering/SceneGraph/IGeometryNode.cs b/src/Avalonia.Visuals/Rendering/SceneGraph/IGeometryNode.cs
new file mode 100644
index 0000000000..4a9daf0ec9
--- /dev/null
+++ b/src/Avalonia.Visuals/Rendering/SceneGraph/IGeometryNode.cs
@@ -0,0 +1,24 @@
+// Copyright (c) The Avalonia Project. All rights reserved.
+// Licensed under the MIT license. See licence.md file in the project root for full license information.
+
+using System;
+
+namespace Avalonia.Rendering.SceneGraph
+{
+    /// <summary>
+    /// Represents a node in the low-level scene graph that represents geometry.
+    /// </summary>
+    public interface IGeometryNode : ISceneNode
+    {
+        /// <summary>
+        /// Hit test the geometry in this node.
+        /// </summary>
+        /// <param name="p">The point in global coordinates.</param>
+        /// <returns>True if the point hits the node's geometry; otherwise false.</returns>
+        /// <remarks>
+        /// This method does not recurse to child <see cref="IVisualNode"/>s, if you want
+        /// to hit test children they must be hit tested manually.
+        /// </remarks>
+        bool HitTest(Point p);
+    }
+}
diff --git a/src/Avalonia.Visuals/Rendering/SceneGraph/ISceneNode.cs b/src/Avalonia.Visuals/Rendering/SceneGraph/ISceneNode.cs
index f6586c1980..37fa5a9463 100644
--- a/src/Avalonia.Visuals/Rendering/SceneGraph/ISceneNode.cs
+++ b/src/Avalonia.Visuals/Rendering/SceneGraph/ISceneNode.cs
@@ -6,8 +6,15 @@ using Avalonia.Media;
 
 namespace Avalonia.Rendering.SceneGraph
 {
+    /// <summary>
+    /// Represents a node in the low-level scene graph.
+    /// </summary>
     public interface ISceneNode
     {
+        /// <summary>
+        /// Renders the node to a drawing context.
+        /// </summary>
+        /// <param name="context">The drawing context.</param>
         void Render(IDrawingContextImpl context);
     }
 }
diff --git a/src/Avalonia.Visuals/Rendering/SceneGraph/IVisualNode.cs b/src/Avalonia.Visuals/Rendering/SceneGraph/IVisualNode.cs
index a402af100d..b52872d9c2 100644
--- a/src/Avalonia.Visuals/Rendering/SceneGraph/IVisualNode.cs
+++ b/src/Avalonia.Visuals/Rendering/SceneGraph/IVisualNode.cs
@@ -7,15 +7,54 @@ using Avalonia.VisualTree;
 
 namespace Avalonia.Rendering.SceneGraph
 {
+    /// <summary>
+    /// Represents a node in the low-level scene graph representing an <see cref="IVisual"/>.
+    /// </summary>
     public interface IVisualNode : ISceneNode
     {
+        /// <summary>
+        /// Gets the visual to which the node relates.
+        /// </summary>
         IVisual Visual { get; }
+
+        /// <summary>
+        /// Gets the parent scene graph node.
+        /// </summary>
         IVisualNode Parent { get; }
+
+        /// <summary>
+        /// Gets the transform for the node from global to control coordinates.
+        /// </summary>
         Matrix Transform { get; }
+
+        /// <summary>
+        /// Gets the clip bounds for the node in global coordinates.
+        /// </summary>
+        /// <remarks>
+        /// This clip does not take into account parent clips, to find the absolute clip bounds
+        /// it is necessary to traverse the tree.
+        /// </remarks>
         Rect ClipBounds { get; }
+
+        /// <summary>
+        /// Whether the node is clipped to <see cref="ClipBounds"/>.
+        /// </summary>
         bool ClipToBounds { get; }
+
+        /// <summary>
+        /// Gets the child scene graph nodes.
+        /// </summary>
         IReadOnlyList<ISceneNode> Children { get; }
 
+        /// <summary>
+        /// Hit test the geometry in this node.
+        /// </summary>
+        /// <param name="p">The point in global coordinates.</param>
+        /// <returns>True if the point hits the node's geometry; otherwise false.</returns>
+        /// <remarks>
+        /// This method does not recurse to child <see cref="IVisualNode"/>s, if you want
+        /// to hit test children they must be hit tested manually.
+        /// </remarks>
         bool HitTest(Point p);
     }
 }
diff --git a/src/Avalonia.Visuals/Rendering/SceneGraph/ImageNode.cs b/src/Avalonia.Visuals/Rendering/SceneGraph/ImageNode.cs
index 3d861279c3..557476636d 100644
--- a/src/Avalonia.Visuals/Rendering/SceneGraph/ImageNode.cs
+++ b/src/Avalonia.Visuals/Rendering/SceneGraph/ImageNode.cs
@@ -7,7 +7,7 @@ using Avalonia.Platform;
 
 namespace Avalonia.Rendering.SceneGraph
 {
-    public class ImageNode : IDrawNode
+    public class ImageNode : IGeometryNode
     {
         public ImageNode(Matrix transform, IBitmapImpl source, double opacity, Rect sourceRect, Rect destRect)
         {
diff --git a/src/Avalonia.Visuals/Rendering/SceneGraph/LineNode.cs b/src/Avalonia.Visuals/Rendering/SceneGraph/LineNode.cs
index 84f08b0efe..d49b75c370 100644
--- a/src/Avalonia.Visuals/Rendering/SceneGraph/LineNode.cs
+++ b/src/Avalonia.Visuals/Rendering/SceneGraph/LineNode.cs
@@ -6,7 +6,7 @@ using Avalonia.Media;
 
 namespace Avalonia.Rendering.SceneGraph
 {
-    public class LineNode : IDrawNode
+    public class LineNode : IGeometryNode
     {
         public LineNode(Matrix transform, Pen pen, Point p1, Point p2)
         {
diff --git a/src/Avalonia.Visuals/Rendering/SceneGraph/RectangleNode.cs b/src/Avalonia.Visuals/Rendering/SceneGraph/RectangleNode.cs
index f059c1c2d6..4e8da4d461 100644
--- a/src/Avalonia.Visuals/Rendering/SceneGraph/RectangleNode.cs
+++ b/src/Avalonia.Visuals/Rendering/SceneGraph/RectangleNode.cs
@@ -6,7 +6,7 @@ using Avalonia.Media;
 
 namespace Avalonia.Rendering.SceneGraph
 {
-    public class RectangleNode : IDrawNode
+    public class RectangleNode : IGeometryNode
     {
         public RectangleNode(Matrix transform, IBrush brush, Pen pen, Rect rect, float cornerRadius)
         {
diff --git a/src/Avalonia.Visuals/Rendering/SceneGraph/TextNode.cs b/src/Avalonia.Visuals/Rendering/SceneGraph/TextNode.cs
index c7fae32769..fbe9bb7176 100644
--- a/src/Avalonia.Visuals/Rendering/SceneGraph/TextNode.cs
+++ b/src/Avalonia.Visuals/Rendering/SceneGraph/TextNode.cs
@@ -7,7 +7,7 @@ using Avalonia.Platform;
 
 namespace Avalonia.Rendering.SceneGraph
 {
-    public class TextNode : IDrawNode
+    public class TextNode : IGeometryNode
     {
         public TextNode(Matrix transform, IBrush foreground, Point origin, IFormattedTextImpl text)
         {
diff --git a/src/Avalonia.Visuals/Rendering/SceneGraph/VisualNode.cs b/src/Avalonia.Visuals/Rendering/SceneGraph/VisualNode.cs
index 1dbf30a7b9..9faaefa2aa 100644
--- a/src/Avalonia.Visuals/Rendering/SceneGraph/VisualNode.cs
+++ b/src/Avalonia.Visuals/Rendering/SceneGraph/VisualNode.cs
@@ -8,10 +8,20 @@ using Avalonia.VisualTree;
 
 namespace Avalonia.Rendering.SceneGraph
 {
+    /// <summary>
+    /// A node in the low-level scene graph representing an <see cref="IVisual"/>.
+    /// </summary>
     public class VisualNode : IVisualNode
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="VisualNode"/> class.
+        /// </summary>
+        /// <param name="visual">The visual that this node represents.</param>
+        /// <param name="parent">The parent scene graph node, if any.</param>
         public VisualNode(IVisual visual, IVisualNode parent)
         {
+            Contract.Requires<ArgumentNullException>(visual != null);
+
             if (parent == null && visual.VisualParent != null)
             {
                 throw new AvaloniaInternalException(
@@ -23,19 +33,53 @@ namespace Avalonia.Rendering.SceneGraph
             Children = new List<ISceneNode>();
         }
 
+        /// <inheritdoc/>
         public IVisual Visual { get; }
+
+        /// <inheritdoc/>
         public IVisualNode Parent { get; }
+
+        /// <inheritdoc/>
         public Matrix Transform { get; set; }
+
+        /// <inheritdoc/>
         public Rect ClipBounds { get; set; }
+
+        /// <inheritdoc/>
         public bool ClipToBounds { get; set; }
+
+        /// <inheritdoc/>
         public Geometry GeometryClip { get; set; }
+
+        /// <summary>
+        /// Gets or sets the opacity of the scnee graph node.
+        /// </summary>
         public double Opacity { get; set; }
+
+        /// <summary>
+        /// Gets or sets the opacity mask for the scnee graph node.
+        /// </summary>
         public IBrush OpacityMask { get; set; }
+
+        /// <summary>
+        /// Gets the child scene graph nodes.
+        /// </summary>
         public List<ISceneNode> Children { get; }
+
+        /// <summary>
+        /// Gets a value indicating whether this node in the scene graph has already
+        /// been updated in the current update pass.
+        /// </summary>
         public bool SubTreeUpdated { get; set; }
 
+        /// <inheritdoc/>
         IReadOnlyList<ISceneNode> IVisualNode.Children => Children;
 
+        /// <summary>
+        /// Makes a copy of the node
+        /// </summary>
+        /// <param name="parent">The new parent node.</param>
+        /// <returns>A cloned node.</returns>
         public VisualNode Clone(IVisualNode parent)
         {
             return new VisualNode(Visual, parent)
@@ -49,13 +93,14 @@ namespace Avalonia.Rendering.SceneGraph
             };
         }
 
+        /// <inheritdoc/>
         public bool HitTest(Point p)
         {
             foreach (var child in Children)
             {
-                var drawNode = child as IDrawNode;
+                var geometry = child as IGeometryNode;
 
-                if (drawNode?.HitTest(p) == true)
+                if (geometry?.HitTest(p) == true)
                 {
                     return true;
                 }