Added some documentation to value stores.

donandren · Jan 20, 2020 · 69e7023 · 69e7023
1 parent 4cc378e
commit 69e7023
Show file tree

Hide file tree

Showing 8 changed files with 60 additions and 3 deletions.
diff --git a/src/Avalonia.Base/PropertyStore/BindingEntry.cs b/src/Avalonia.Base/PropertyStore/BindingEntry.cs
@@ -6,10 +6,17 @@
 
 namespace Avalonia.PropertyStore
 {
+    /// <summary>
+    /// Represents an untyped interface to <see cref="BindingEntry{T}"/>.
+    /// </summary>
     internal interface IBindingEntry : IPriorityValueEntry, IDisposable
     {
     }
 
+    /// <summary>
+    /// Stores a binding in a <see cref="ValueStore"/> or <see cref="PriorityValue{T}"/>.
+    /// </summary>
+    /// <typeparam name="T">The property type.</typeparam>
     internal class BindingEntry<T> : IBindingEntry, IPriorityValueEntry<T>, IObserver<BindingValue<T>>
     {
         private IValueSink _sink;

diff --git a/src/Avalonia.Base/PropertyStore/ConstantValueEntry.cs b/src/Avalonia.Base/PropertyStore/ConstantValueEntry.cs
@@ -5,6 +5,11 @@
 
 namespace Avalonia.PropertyStore
 {
+    /// <summary>
+    /// Stores a value with a priority in a <see cref="ValueStore"/> or
+    /// <see cref="PriorityValue{T}"/>.
+    /// </summary>
+    /// <typeparam name="T">The property type.</typeparam>
     internal class ConstantValueEntry<T> : IPriorityValueEntry<T>
     {
         public ConstantValueEntry(

diff --git a/src/Avalonia.Base/PropertyStore/IPriorityValueEntry.cs b/src/Avalonia.Base/PropertyStore/IPriorityValueEntry.cs
@@ -5,13 +5,20 @@
 
 namespace Avalonia.PropertyStore
 {
+    /// <summary>
+    /// Represents an untyped interface to <see cref="IPriorityValueEntry{T}"/>.
+    /// </summary>
     internal interface IPriorityValueEntry : IValue
     {
         BindingPriority Priority { get; }
 
         void Reparent(IValueSink sink);
     }
 
+    /// <summary>
+    /// Represents an object that can act as an entry in a <see cref="PriorityValue{T}"/>.
+    /// </summary>
+    /// <typeparam name="T">The property type.</typeparam>
     internal interface IPriorityValueEntry<T> : IPriorityValueEntry, IValue<T>
     {
     }

diff --git a/src/Avalonia.Base/PropertyStore/IValue.cs b/src/Avalonia.Base/PropertyStore/IValue.cs
@@ -4,12 +4,19 @@
 
 namespace Avalonia.PropertyStore
 {
+    /// <summary>
+    /// Represents an untyped interface to <see cref="IValue{T}"/>.
+    /// </summary>
     internal interface IValue
     {
         Optional<object> Value { get; }
         BindingPriority ValuePriority { get; }
     }
 
+    /// <summary>
+    /// Represents an object that can act as an entry in a <see cref="ValueStore"/>.
+    /// </summary>
+    /// <typeparam name="T">The property type.</typeparam>
     internal interface IValue<T> : IValue
     {
         new Optional<T> Value { get; }

diff --git a/src/Avalonia.Base/PropertyStore/IValueSink.cs b/src/Avalonia.Base/PropertyStore/IValueSink.cs
@@ -1,10 +1,12 @@
-using System;
-using Avalonia.Data;
+using Avalonia.Data;
 
 #nullable enable
 
 namespace Avalonia.PropertyStore
 {
+    /// <summary>
+    /// Represents an entity that can receive change notifications in a <see cref="ValueStore"/>.
+    /// </summary>
     internal interface IValueSink
     {
         void ValueChanged<T>(

diff --git a/src/Avalonia.Base/PropertyStore/LocalValueEntry.cs b/src/Avalonia.Base/PropertyStore/LocalValueEntry.cs
@@ -4,6 +4,11 @@
 
 namespace Avalonia.PropertyStore
 {
+    /// <summary>
+    /// Stores a value with local value priority in a <see cref="ValueStore"/> or
+    /// <see cref="PriorityValue{T}"/>.
+    /// </summary>
+    /// <typeparam name="T">The property type.</typeparam>
     internal class LocalValueEntry<T> : IValue<T>
     {
         private T _value;

diff --git a/src/Avalonia.Base/PropertyStore/PriorityValue.cs b/src/Avalonia.Base/PropertyStore/PriorityValue.cs
@@ -6,6 +6,17 @@
 
 namespace Avalonia.PropertyStore
 {
+    /// <summary>
+    /// Stores a set of prioritized values and bindings in a <see cref="ValueStore"/>.
+    /// </summary>
+    /// <typeparam name="T">The property type.</typeparam>
+    /// <remarks>
+    /// When more than a single value or binding is applied to a property in an
+    /// <see cref="AvaloniaObject"/>, the entry in the <see cref="ValueStore"/> is converted into
+    /// a <see cref="PriorityValue{T}"/>. This class holds any number of
+    /// <see cref="IPriorityValueEntry{T}"/> entries (sorted first by priority and then in the order
+    /// they were added) plus a local value.
+    /// </remarks>
     internal class PriorityValue<T> : IValue<T>, IValueSink
     {
         private readonly IValueSink _sink;

diff --git a/src/Avalonia.Base/ValueStore.cs b/src/Avalonia.Base/ValueStore.cs
@@ -1,5 +1,4 @@
 using System;
-using System.Collections.Generic;
 using Avalonia.Data;
 using Avalonia.PropertyStore;
 using Avalonia.Utilities;
@@ -8,6 +7,20 @@
 
 namespace Avalonia
 {
+    /// <summary>
+    /// Stores styled property values for an <see cref="AvaloniaObject"/>.
+    /// </summary>
+    /// <remarks>
+    /// At its core this class consists of an <see cref="AvaloniaProperty"/> to 
+    /// <see cref="IValue"/> mapping which holds the current values for each set property. This
+    /// <see cref="IValue"/> can be in one of 4 states:
+    /// 
+    /// - For a single local value it will be an instance of <see cref="LocalValueEntry{T}"/>.
+    /// - For a single value of a priority other than LocalValue it will be an instance of
+    ///   <see cref="ConstantValueEntry{T}"/>`
+    /// - For a single binding it will be an instance of <see cref="BindingEntry{T}"/>
+    /// - For all other cases it will be an instance of <see cref="PriorityValue{T}"/>
+    /// </remarks>
     internal class ValueStore : IValueSink
     {
         private readonly AvaloniaObject _owner;