Add documentation comments to various binding-related classes

Part is taken from #1392 which won't be merged for a while.

Author: exyi

src/Framework/Core/ViewModel/AllowStaticCommandAttribute.cs

@@ -3,6 +3,11 @@
 
 namespace DotVVM.Framework.ViewModel
 {
+    /// <summary> Allows DotVVM to call the method from staticCommand. </summary>
+    /// <remarks>
+    /// This attribute must be used to prevent attackers from calling any method in your system.
+    /// While DotVVM signs the method names used staticCommand and it shouldn't be possible to execute any other method,
+    /// the attribute offers a decent protection against RCE in case the Asp.Net Core encryption keys are compromised. </remarks>
     public class AllowStaticCommandAttribute : Attribute
     {
     }

src/Framework/Core/ViewModel/Direction.cs

@@ -5,19 +5,31 @@
 namespace DotVVM.Framework.ViewModel
 {
     ///<summary>
-    /// ServerToClient, ServerToClient on postback, ClientToServer, C2S iff in command path
+    /// Specifies on which requests should the property should serialized and sent. Default is <see cref="Direction.Both">Both</see>.
+    /// Set to <see cref="Direction.None">None</see> to disable serialization of the property.
+    /// This enums is flags, the directions can be arbitrarily combined.
     ///</summary>
     [Flags]
     public enum Direction
     {
+        /// <summary> Never send this property to the client, it won't be allowed to use this property from value and staticCommand bindings. </summary>
         None = 0,
+        /// <summary> Sent to client on the initial GET request, but not sent again on postbacks </summary>
         ServerToClientFirstRequest = 1,
+        /// <summary> Property is updated on postbacks, but not sent on the first request (initially it will be set to null or default value of the primitive type) </summary>
         ServerToClientPostback = 2,
+        /// <summary> Sent from server to client, but not sent back. </summary>
         ServerToClient = ServerToClientFirstRequest | ServerToClientPostback,
+        /// <summary> Complement to <see cref="ClientToServerInPostbackPath" />, not meant to be used on its own. </summary>
         ClientToServerNotInPostbackPath = 4,
+        /// <summary> Sent from client to server, but only if the current data context is this property. If the data context is a child object of this property, only that part of the object will be sent, all other properties are ignored.
+        /// To sent the initial value to client, use <c>Direction.ServerToClientFirstRequest | Direction.ClientToServerInPostbackPath</c> </summary>
         ClientToServerInPostbackPath = 8,
+        /// <summary> Sent back on postbacks. Initially the property will set to null or primitive default value. To send the initial value to client, use <c>Direction.ServerToClientFirstRequest | Direction.ClientToServer</c> </summary>
         ClientToServer = ClientToServerInPostbackPath | ClientToServerNotInPostbackPath,
+        /// <summary> Always sent to client, sent back only when the object is the current data context (see also <see cref="ClientToServerInPostbackPath"/>) </summary>
         IfInPostbackPath = ServerToClient | ClientToServerInPostbackPath,
+        /// <summary> Value is sent on each request. This is the default value. </summary>
         Both = 15,
     }
-}
+}

src/Framework/Core/ViewModel/ProtectMode.cs

@@ -11,17 +11,17 @@ namespace DotVVM.Framework.ViewModel
     public enum ProtectMode
     {
         /// <summary>
-        /// The property value is sent to the client unencrypted and it is not signed. It can be modified on the client with no restrictions.
+        /// The property value is sent to the client unencrypted and it is not signed. It can be modified on the client with no restrictions. This is the default.
         /// </summary>
         None,
 
         /// <summary>
-        /// The property value is sent to the client unencrypted, but it is also signed. If it is modified on the client, the server will throw an exception during postback.
+        /// The property value is sent to the client in both unencrypted and encrypted form. On server, the encrypted value is read, so it cannot be modified on the client.
         /// </summary>
         SignData,
 
         /// <summary>
-        /// The property value is encrypted before it is sent to the client.
+        /// The property value is encrypted before it is sent to the client. Encrypted properties thus cannot be used in value bindings.
         /// </summary>
         EncryptData
     }

src/Framework/Framework/Binding/ActiveDotvvmProperty.cs

@@ -10,6 +10,7 @@
 
 namespace DotVVM.Framework.Binding
 {
+    /// <summary> An abstract DotvvmProperty which contains code to be executed when the assigned control is being rendered. </summary>
     public abstract class ActiveDotvvmProperty : DotvvmProperty
     {
         public abstract void AddAttributesToRender(IHtmlWriter writer, IDotvvmRequestContext context, DotvvmControl control);

src/Framework/Framework/Binding/AttachedPropertyAttribute.cs

@@ -6,6 +6,8 @@
 
 namespace DotVVM.Framework.Binding
 {
+    /// <summary> Used to mark DotvvmProperty which are used on other control than the declaring type. For example, Validation.Target is an attached property. </summary>
+    /// <remark> Note that DotVVM allows this for any DotvvmProperty, but this attribute instructs editor extension to include the property in autocompletion. </remark>
     [AttributeUsage(AttributeTargets.Field, AllowMultiple = false)]
     public class AttachedPropertyAttribute : Attribute
     {

src/Framework/Framework/Binding/BindingCompilationOptionsAttribute.cs

@@ -1,11 +1,18 @@
 using System;
 using System.Collections.Generic;
 using System.Text;
+using DotVVM.Framework.Binding.Expressions;
+using DotVVM.Framework.Compilation.Binding;
 
 namespace DotVVM.Framework.Binding
 {
+    /// <summary> Allow to adjust how bindings are compiled. Can be placed on custom binding type (for example, see <see cref="ValueBindingExpression" />) or on a dotvvm property </summary>
     public abstract class BindingCompilationOptionsAttribute : Attribute
     {
+        /// <summary> Returns a list of resolvers - functions which accept any set of existing binding properties and returns one new binding property.
+        /// It will be automatically invoked when the returned property is needed.
+        /// See <see cref="BindingPropertyResolvers" /> for a list of default property resolvers - to adjust how the binding is compiled, you'll want to redefine one of the default resolvers.
+        /// See <see cref="StaticCommandBindingExpression.OptionsAttribute" /> for example how to use this method. </summary>
         public abstract IEnumerable<Delegate> GetResolvers();
     }
 }

src/Framework/Framework/Binding/BindingCompilationService.cs

@@ -26,10 +26,13 @@ public class BindingCompilationOptions
         public List<object> TransformerClasses { get; set; } = new List<object>();
     }
 
+    /// <summary> A service used to create new bindings and compute binding properties. </summary>
     public class BindingCompilationService
     {
         private readonly IExpressionToDelegateCompiler expressionCompiler;
         private readonly Lazy<BindingCompilationService> noInitService;
+
+        /// <summary> Utilities for caching bindings created at runtime </summary>
         public DotvvmBindingCacheHelper Cache { get; }
 
         public BindingCompilationService(IOptions<BindingCompilationOptions> options, IExpressionToDelegateCompiler expressionCompiler, IDotvvmCacheAdapter cache)
@@ -123,7 +126,7 @@ public BindingCompilationRequirementsAttribute GetRequirements(IBinding binding,
         }
 
         /// <summary>
-        /// Resolves required and optional properties
+        /// Resolves required properties of the binding. If the binding contains <see cref="BindingErrorReporterProperty" /> it will be used to report errors instead of throwing an exception.
         /// </summary>
         public virtual void InitializeBinding(IBinding binding, IEnumerable<BindingCompilationRequirementsAttribute>? bindingRequirements = null)
         {

src/Framework/Framework/Binding/BindingHelper.cs

@@ -24,8 +24,10 @@ namespace DotVVM.Framework.Binding
 {
     public static partial class BindingHelper
     {
+        /// <summary> Gets the binding property identified by the type. The result may be null, if <paramref name="errorMode"/> is <see cref="ErrorHandlingMode.ReturnNull">ReturnNul</see> This method should always return the same result and should run fast (may rely on caching, so first call might not be that fast). </summary>
         [return: MaybeNull]
-        public static T GetProperty<T>(this IBinding binding, ErrorHandlingMode errorMode = ErrorHandlingMode.ThrowException) => (T)binding.GetProperty(typeof(T), errorMode)!;
+        public static T GetProperty<T>(this IBinding binding, ErrorHandlingMode errorMode) => (T)binding.GetProperty(typeof(T), errorMode)!;
+        /// <summary> Gets the binding property identified by the type. This method should always return the same result and should run fast (may rely on caching, so first call might not be that fast). </summary>
         public static T GetProperty<T>(this IBinding binding) => GetProperty<T>(binding, ErrorHandlingMode.ThrowException)!;
 
         [Obsolete]

src/Framework/Framework/Binding/BindingPageInfo.cs

@@ -11,8 +11,11 @@ namespace DotVVM.Framework.Binding
 {
     public class BindingPageInfo
     {
+        /// <summary> Returns true if any command or staticCommand is currently running. Always returns false on the server. </summary>
         public bool IsPostbackRunning => false;
+        /// <summary> Returns true on server and false in JavaScript. </summary>
         public bool EvaluatingOnServer => true;
+        /// <summary> Returns false on server and true in JavaScript. </summary>
         public bool EvaluatingOnClient => false;
 
         internal static void RegisterJavascriptTranslations(JavascriptTranslatableMethodCollection methods)

src/Framework/Framework/Binding/CollectionElementDataContextChangeAttribute.cs

@@ -10,6 +10,7 @@
 
 namespace DotVVM.Framework.Binding
 {
+    /// <summary> Sets data context type to the element type of current data context. </summary>
     public class CollectionElementDataContextChangeAttribute : DataContextChangeAttribute
     {
         public override int Order { get; }