From 2cd5d48428980fffbf5459c6a8f18413bce9b43f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Standa=20Luke=C5=A1?= <exyi@outlook.cz>
Date: Sun, 1 Oct 2023 13:17:23 +0200
Subject: [PATCH] Add documentation comments to the KnockoutBindingGroup

---
 .../Framework/Controls/KnockoutBindingGroup.cs  | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/src/Framework/Framework/Controls/KnockoutBindingGroup.cs b/src/Framework/Framework/Controls/KnockoutBindingGroup.cs
index bd6a6eadbf..aadc0a5c07 100644
--- a/src/Framework/Framework/Controls/KnockoutBindingGroup.cs
+++ b/src/Framework/Framework/Controls/KnockoutBindingGroup.cs
@@ -9,13 +9,15 @@
 
 namespace DotVVM.Framework.Controls
 {
+    /// <summary> Represents a JS object holding multiple binding expressions or constant values. The binding handler will receive the JS object with the evaluated bindings, or the constants provided to the KnockoutBindingGroup.Add method. The group can either be passed to IHtmlWriter or converted into a string expression using <see cref="ToString()"/> </summary>
     public class KnockoutBindingGroup: IEnumerable<KnockoutBindingGroup.KnockoutBindingInfo>
     {
-
-        private List<KnockoutBindingInfo> entries = new List<KnockoutBindingInfo>();
-        
+        private readonly List<KnockoutBindingInfo> entries = new List<KnockoutBindingInfo>();
         public bool IsEmpty => entries.Count == 0;
+        public int Count => entries.Count;
+
 
+        /// <summary> Adds value of the specified dotvvm <paramref name="property"/>. If the property contains a value binding, the JS expression is added to the group. Otherwise, the JSON serialized constant value is added. </summary>
         public virtual void Add(string name, DotvvmControl control, DotvvmProperty property, Action? nullBindingAction = null)
         {
             var binding = control.GetValueBinding(property);
@@ -30,17 +32,20 @@ public virtual void Add(string name, DotvvmControl control, DotvvmProperty prope
             }
         }
 
+        /// <summary> Adds the JS <paramref name="expression"/> to the group. </summary>
         public virtual void Add(string name, string expression)
         {
             entries.Add(new KnockoutBindingInfo(name, expression));
         }
 
+        /// <summary> Adds another nested group. If the nested group is empty, nothing is added (undefined will be in the field). </summary>
         public void Add(string name, KnockoutBindingGroup nestedGroup)
         {
             if (!nestedGroup.IsEmpty)
                 Add(name, nestedGroup.ToString());
         }
 
+        /// <summary> Adds a knockout binding expression of the specified value binding. </summary>
         public void Add(string name, DotvvmBindableObject contextControl, IValueBinding binding)
         {
             var expression = binding.GetKnockoutBindingExpression(contextControl);
@@ -56,12 +61,14 @@ public virtual void Add(string name, string expression, bool surroundWithDoubleQ
                 Add(name, expression);
         }
 
+        /// <summary> Adds the specified value as a JSON serialized constant expression. </summary>
         public virtual void AddValue(string name, object? value)
         {
             var expression = JsonConvert.SerializeObject(value, DefaultSerializerSettingsProvider.Instance.Settings);
             Add(name, expression);
         }
 
+        /// <summary> Copies all fields from the <paramref name="other"/> binding group. </summary>
         public virtual void AddFrom(KnockoutBindingGroup other)
         {
             entries.AddRange(other.entries);
@@ -74,6 +81,7 @@ protected virtual string GetKnockoutBindingExpression(DotvvmBindableObject obj,
             return valueBinding.GetKnockoutBindingExpression(obj);
         }
 
+        /// <summary> Returns the JS object expression with the <c>Add</c>ed fields. </summary>
         public override string ToString()
         {
             if (entries.Count == 0) return "{}";
@@ -84,6 +92,7 @@ public override string ToString()
 
         IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
 
+        /// <summary> A named expression - a field in the <see cref="KnockoutBindingGroup" /> </summary>
         public class KnockoutBindingInfo
         {
             public KnockoutBindingInfo(string name, string expression)
@@ -92,7 +101,9 @@ public KnockoutBindingInfo(string name, string expression)
                 Expression = expression;
             }
 
+            /// <summary> The field name in the resulting JS object. </summary>
             public string Name { get; }
+            /// <summary> JS expression returning the desired value. </summary>
             public string Expression { get; }
 
             public override string ToString()