Improve XML docs

Author: marcel2215

ChatAIze.PluginApi/ActionResult.cs

@@ -3,8 +3,18 @@
 namespace ChatAIze.PluginApi;
 
 /// <summary>
-/// Represents the result of an action execution, including its identifier, outcome value, and success flag.
+/// Serializable action result value object (id + result payload + success flag).
 /// </summary>
+/// <remarks>
+/// <para>
+/// This type is primarily a convenience DTO for plugin authors (for example: returning a list of results from a custom tool/function).
+/// </para>
+/// <para>
+/// In ChatAIze.Chatbot, workflow execution produces results implementing <see cref="ChatAIze.Abstractions.Chat.IActionResult"/>.
+/// While this <see cref="ActionResult"/> record does not implement that interface, it intentionally mirrors the same shape and
+/// is safe to serialize.
+/// </para>
+/// </remarks>
 public record ActionResult
 {
     /// <summary>

ChatAIze.PluginApi/ChatFunction.cs

@@ -7,8 +7,45 @@
 namespace ChatAIze.PluginApi;
 
 /// <summary>
-/// Represents a chatbot function implementation that includes its name, description, execution delegate, parameters, and behavioral flags.
+/// Convenience implementation of <see cref="IChatFunction"/> used to expose plugin capabilities as LLM tools.
 /// </summary>
+/// <remarks>
+/// <para>
+/// In ChatAIze.Chatbot, functions returned by <see cref="ChatAIze.Abstractions.Plugins.IChatbotPlugin.FunctionsCallback"/> become model-callable tools.
+/// When a tool call happens, the host invokes <see cref="IChatFunction.Callback"/> using
+/// <see cref="ChatAIze.Utilities.Extensions.DelegateExtensions.InvokeForStringResultAsync(Delegate, string, IFunctionContext?, CancellationToken)"/>.
+/// </para>
+/// <para>
+/// Parameter schema:
+/// <list type="bullet">
+/// <item><description>If <see cref="Parameters"/> is provided (non-null), the host uses it to build the JSON schema shown to the model.</description></item>
+/// <item><description>If <see cref="Parameters"/> is <see langword="null"/>, the schema is derived from <see cref="Callback"/> via reflection.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// If your delegate accepts injected parameters, prefer supplying an explicit <see cref="Parameters"/> list so injected parameters are not
+/// presented as user-provided inputs.
+/// Note: the current schema serializer excludes <see cref="CancellationToken"/> automatically, but it does not exclude
+/// <see cref="IFunctionContext"/>. If your callback accepts <see cref="IFunctionContext"/>, you should provide <see cref="Parameters"/> explicitly
+/// to avoid confusing tool schemas.
+/// </para>
+/// <para>
+/// When relying on reflection-based schemas, you can improve the model-visible descriptions and constraints by annotating your callback with:
+/// <list type="bullet">
+/// <item><description><see cref="DescriptionAttribute"/> on the method and/or parameters,</description></item>
+/// <item><description>data annotations such as <c>[Required]</c>, <c>[MinLength]</c>, <c>[MaxLength]</c>, <c>[StringLength]</c> on string parameters.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// Return values: if the callback returns a non-string value, the host serializes it to JSON for tool output using snake_case property names.
+/// </para>
+/// <para>
+/// Error handling (provider-specific):
+/// tool execution is considered successful by the OpenAI provider when the returned string does not start with <c>"Error:"</c>
+/// (case-insensitive). This convention is used to decide whether any tool call "succeeded" in a completion.
+/// For recoverable failures, prefer returning <c>"Error: ..."</c> instead of throwing, so the model can retry with corrected input.
+/// </para>
+/// </remarks>
 public class ChatFunction : IChatFunction
 {
     /// <summary>
@@ -21,8 +58,8 @@ public ChatFunction() { }
     /// </summary>
     /// <param name="callback">The delegate that contains the function logic.</param>
     /// <remarks>
-    /// The function name is inferred from the delegate method name. If the method is decorated with a <see cref="DescriptionAttribute"/>,
-    /// its description is used automatically.
+    /// The function name is inferred from the delegate method name (using ChatAIze normalization).
+    /// If the method is decorated with a <see cref="DescriptionAttribute"/>, its description is used automatically.
     /// </remarks>
     [SetsRequiredMembers]
     public ChatFunction(Delegate callback)
@@ -37,9 +74,9 @@ public ChatFunction(Delegate callback)
     /// </summary>
     /// <param name="name">The unique name of the function.</param>
     /// <param name="description">Optional description for the function.</param>
-    /// <param name="requiresDoubleCheck">A flag indicating whether double confirmation is required before execution.</param>
+    /// <param name="requiresDoubleCheck">A flag indicating whether the model should be asked to confirm by calling the function twice.</param>
     /// <param name="callback">The delegate that contains the function's logic.</param>
-    /// <param name="parameters">Optional parameters expected by the function.</param>
+    /// <param name="parameters">Optional explicit parameters expected by the function (controls schema generation).</param>
     [SetsRequiredMembers]
     public ChatFunction(
         string name,
@@ -56,12 +93,20 @@ public ChatFunction(
     }
 
     /// <inheritdoc />
+    /// <remarks>
+    /// In ChatAIze.Chatbot the name is normalized to snake_case when exposed to the model.
+    /// Choose a stable, unique name across all installed plugins.
+    /// </remarks>
     public virtual required string Name { get; set; }
 
     /// <inheritdoc />
     public virtual string? Description { get; set; }
 
     /// <inheritdoc />
+    /// <remarks>
+    /// In the OpenAI and Gemini providers, enabling this flag causes an extra model round-trip:
+    /// the model is instructed to call the function again to confirm intent before the callback is executed.
+    /// </remarks>
     public virtual bool RequiresDoubleCheck { get; set; }
 
     /// <inheritdoc />
@@ -70,6 +115,16 @@ public ChatFunction(
     /// <summary>
     /// Gets or sets the list of parameters expected by this function.
     /// </summary>
+    /// <remarks>
+    /// Provide this list when you want full control over:
+    /// <list type="bullet">
+    /// <item><description>names and descriptions shown to the model,</description></item>
+    /// <item><description>which parameters are required,</description></item>
+    /// <item><description>enum value lists,</description></item>
+    /// <item><description>and avoiding injected parameters (for example <see cref="IFunctionContext"/>).</description></item>
+    /// </list>
+    /// When <see langword="null"/>, the host derives the schema from <see cref="Callback"/> parameters.
+    /// </remarks>
     public virtual ICollection<IFunctionParameter>? Parameters { get; set; }
 
     /// <inheritdoc />

ChatAIze.PluginApi/ChatbotPlugin.cs

@@ -8,13 +8,39 @@
 namespace ChatAIze.PluginApi;
 
 /// <summary>
-/// Represents a chatbot plugin implementation that provides settings, functions, actions, and conditions to extend chatbot capabilities.
+/// Convenience base implementation of <see cref="IChatbotPlugin"/> for ChatAIze.Chatbot plugins.
 /// </summary>
+/// <remarks>
+/// <para>
+/// In ChatAIze.Chatbot, plugins are loaded from a DLL in the <c>plugins</c> folder (or uploaded through the dashboard).
+/// The host discovers a plugin in this order:
+/// <list type="number">
+/// <item><description>a type implementing <see cref="IAsyncPluginLoader"/> (async factory),</description></item>
+/// <item><description>a type implementing <see cref="IPluginLoader"/> (sync factory),</description></item>
+/// <item><description>any non-abstract type implementing <see cref="IChatbotPlugin"/> (created via <c>Activator.CreateInstance</c>).</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// A plugin instance is typically a singleton for the lifetime of the host process. Your callbacks and delegates can be invoked
+/// concurrently for multiple chats/users. Avoid storing per-user/per-chat state on the plugin instance; prefer using the
+/// supplied <see cref="IChatContext"/>, <see cref="IChatbotContext"/>, <see cref="IFunctionContext"/>, <see cref="IActionContext"/>,
+/// and <see cref="IConditionContext"/> objects.
+/// </para>
+/// <para>
+/// Settings in ChatAIze.Chatbot are stored in a single key/value dictionary (<see cref="IPluginSettings"/>). Because keys are shared
+/// across all plugins, use stable, globally-unique setting ids (for example: <c>"com.example.my_plugin:api_key"</c>).
+/// </para>
+/// </remarks>
 public class ChatbotPlugin : IChatbotPlugin, IEditableSettingsContainer
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="ChatbotPlugin"/> class with default callbacks.
     /// </summary>
+    /// <remarks>
+    /// The default behavior of this type is "static": each callback returns the corresponding in-memory collection
+    /// (<see cref="Settings"/>, <see cref="Functions"/>, <see cref="Actions"/>, <see cref="Conditions"/>).
+    /// Override the callback properties if you need context-dependent definitions.
+    /// </remarks>
     public ChatbotPlugin()
     {
         SettingsCallback ??= _ => ValueTask.FromResult((IReadOnlyCollection<ISetting>)Settings);
@@ -24,7 +50,7 @@ public ChatbotPlugin()
     }
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="ChatbotPlugin"/> class with metadata and content.
+    /// Initializes a new instance of the <see cref="ChatbotPlugin"/> class with metadata and initial collections.
     /// </summary>
     /// <param name="id">The unique identifier of the plugin.</param>
     /// <param name="title">The display title of the plugin.</param>
@@ -35,10 +61,18 @@ public ChatbotPlugin()
     /// <param name="version">Optional version information (defaults to 1.0.0.0).</param>
     /// <param name="releaseTime">Optional initial release timestamp.</param>
     /// <param name="lastUpdateTime">Optional timestamp of the most recent update.</param>
-    /// <param name="settings">Optional collection of plugin-level settings.</param>
-    /// <param name="functions">Optional collection of chatbot functions provided by the plugin.</param>
-    /// <param name="actions">Optional collection of reusable function actions.</param>
-    /// <param name="conditions">Optional collection of conditional rules used before function execution.</param>
+    /// <param name="settings">Optional collection of plugin-level settings (rendered in the dashboard).</param>
+    /// <param name="functions">Optional collection of chatbot functions (tools) provided by the plugin.</param>
+    /// <param name="actions">Optional collection of reusable workflow actions provided by the plugin.</param>
+    /// <param name="conditions">Optional collection of reusable workflow conditions provided by the plugin.</param>
+    /// <remarks>
+    /// In ChatAIze.Chatbot:
+    /// <list type="bullet">
+    /// <item><description><see cref="SettingsCallback"/> is used to render plugin settings in the dashboard.</description></item>
+    /// <item><description><see cref="FunctionsCallback"/> is used to surface functions as LLM tools (and executed via <see cref="ChatAIze.Utilities.Extensions.DelegateExtensions"/> when <see cref="IChatFunction.Callback"/> is provided).</description></item>
+    /// <item><description><see cref="ActionsCallback"/> / <see cref="ConditionsCallback"/> are used by the workflow engine.</description></item>
+    /// </list>
+    /// </remarks>
     [SetsRequiredMembers]
     public ChatbotPlugin(
         string id,
@@ -101,48 +135,87 @@ public ChatbotPlugin(
     /// <summary>
     /// Gets or sets the collection of settings exposed by the plugin.
     /// </summary>
+    /// <remarks>
+    /// In ChatAIze.Chatbot, settings are rendered in the dashboard and persisted as JSON under <see cref="ISetting.Id"/>.
+    /// Prefer stable ids and prefix them with your plugin id to avoid collisions with other plugins.
+    /// </remarks>
     public virtual ICollection<ISetting> Settings { get; set; } = [];
 
     /// <summary>
     /// Gets or sets the collection of chatbot functions exposed by the plugin.
     /// </summary>
+    /// <remarks>
+    /// These functions are surfaced to the language model as callable tools.
+    /// <para>
+    /// In ChatAIze.Chatbot, a function is only executable if <see cref="IChatFunction.Callback"/> is set (otherwise the host falls back
+    /// to a default callback intended for "integration functions" configured in the dashboard).
+    /// </para>
+    /// </remarks>
     public virtual ICollection<IChatFunction> Functions { get; set; } = [];
 
     /// <summary>
-    /// Gets or sets the collection of reusable function actions provided by the plugin.
+    /// Gets or sets the collection of reusable workflow actions provided by the plugin.
     /// </summary>
+    /// <remarks>
+    /// Actions are building blocks used by ChatAIze.Chatbot "integration functions". They are not surfaced to the model directly.
+    /// </remarks>
     public virtual ICollection<IFunctionAction> Actions { get; set; } = [];
 
     /// <summary>
-    /// Gets or sets the collection of preconditions that can be applied before function execution.
+    /// Gets or sets the collection of reusable workflow conditions provided by the plugin.
     /// </summary>
+    /// <remarks>
+    /// Conditions can be attached to integration functions to allow/deny execution based on settings and chat context.
+    /// </remarks>
     public virtual ICollection<IFunctionCondition> Conditions { get; set; } = [];
 
     /// <inheritdoc />
+    /// <remarks>
+    /// In ChatAIze.Chatbot this callback is invoked while rendering the plugin settings page and when plugin settings change.
+    /// It should be fast and should return deterministic ids.
+    /// </remarks>
     public virtual Func<IChatbotContext, ValueTask<IReadOnlyCollection<ISetting>>> SettingsCallback { get; set; }
 
     /// <inheritdoc />
+    /// <remarks>
+    /// In ChatAIze.Chatbot this callback is invoked when building the tool list for a completion. Return only functions that should be
+    /// available for the current chat/user.
+    /// </remarks>
     public virtual Func<IChatContext, ValueTask<IReadOnlyCollection<IChatFunction>>> FunctionsCallback { get; set; }
 
     /// <inheritdoc />
+    /// <remarks>
+    /// In ChatAIze.Chatbot this callback is invoked when the dashboard or workflow engine needs the list of available actions.
+    /// </remarks>
     public virtual Func<IChatbotContext, ValueTask<IReadOnlyCollection<IFunctionAction>>> ActionsCallback { get; set; }
 
     /// <inheritdoc />
+    /// <remarks>
+    /// In ChatAIze.Chatbot this callback is invoked when the dashboard or workflow engine needs the list of available conditions.
+    /// </remarks>
     public virtual Func<IChatbotContext, ValueTask<IReadOnlyCollection<IFunctionCondition>>> ConditionsCallback { get; set; }
 
     /// <summary>
-    /// Adds a setting to the plugin.
+    /// Adds a setting definition to <see cref="Settings"/>.
     /// </summary>
     /// <param name="setting">The setting to add.</param>
+    /// <remarks>
+    /// Note: the method name contains a historical typo (<c>AddSetttng</c>). It is kept for backwards compatibility.
+    /// You can also add settings via <see cref="IEditableSettingsContainer.Settings"/> or the extension methods in
+    /// <see cref="ChatAIze.PluginApi.Settings.StringSettingExtensions"/>.
+    /// </remarks>
     public virtual void AddSetttng(ISetting setting)
     {
         Settings.Add(setting);
     }
 
     /// <summary>
-    /// Adds a chatbot function to the plugin.
+    /// Adds a chatbot function (tool) to <see cref="Functions"/>.
     /// </summary>
     /// <param name="function">The function to register.</param>
+    /// <remarks>
+    /// In ChatAIze.Chatbot, functions should provide a non-null <see cref="IChatFunction.Callback"/> for the host to execute them.
+    /// </remarks>
     public virtual void AddFunction(IChatFunction function)
     {
         Functions.Add(function);
@@ -152,13 +225,27 @@ public virtual void AddFunction(IChatFunction function)
     /// Adds a chatbot function by wrapping a raw delegate.
     /// </summary>
     /// <param name="function">The function delegate to wrap.</param>
+    /// <remarks>
+    /// This overload creates a <see cref="ChatFunction"/> which:
+    /// <list type="bullet">
+    /// <item><description>derives <see cref="IChatFunction.Name"/> from the method name,</description></item>
+    /// <item><description>uses <see cref="System.ComponentModel.DescriptionAttribute"/> (when present) as the description,</description></item>
+    /// <item><description>stores the delegate as <see cref="IChatFunction.Callback"/> so the host can execute it.</description></item>
+    /// </list>
+    /// The delegate is invoked using ChatAIze's standard binding rules (snake_case arguments, optional <see cref="IFunctionContext"/> and <see cref="CancellationToken"/> injection).
+    /// <para>
+    /// For best results, prefer using a named method. If you pass a lambda or local function, the compiler-generated method name may be unstable;
+    /// ChatAIze attempts to normalize such names but can throw if the pattern is not recognized. If you need full control over the tool name,
+    /// construct a <see cref="ChatFunction"/> with an explicit <see cref="IChatFunction.Name"/> instead.
+    /// </para>
+    /// </remarks>
     public virtual void AddFunction(Delegate function)
     {
         Functions.Add(new ChatFunction(function));
     }
 
     /// <summary>
-    /// Adds a reusable action to the plugin.
+    /// Adds a reusable workflow action to <see cref="Actions"/>.
     /// </summary>
     /// <param name="action">The function action to register.</param>
     public virtual void AddAction(IFunctionAction action)
@@ -167,7 +254,7 @@ public virtual void AddAction(IFunctionAction action)
     }
 
     /// <summary>
-    /// Adds a condition that can be used to restrict function execution.
+    /// Adds a reusable workflow condition to <see cref="Conditions"/>.
     /// </summary>
     /// <param name="condition">The function condition to register.</param>
     public virtual void AddCondition(IFunctionCondition condition)

ChatAIze.PluginApi/Databases/DatabaseFilter.cs

@@ -5,8 +5,12 @@
 namespace ChatAIze.PluginApi.Databases;
 
 /// <summary>
-/// Represents a filter condition used in a database query, including the property, type of comparison, value, and optional modifiers.
+/// Concrete <see cref="IDatabaseFilter"/> used to describe a single filter predicate in a database query.
 /// </summary>
+/// <remarks>
+/// Use this type with database APIs that accept <see cref="IDatabaseFilter"/> (for example via <see cref="ChatAIze.Abstractions.Databases.IDatabaseManager"/>).
+/// The meaning of <see cref="Property"/> and supported <see cref="FilterType"/> values depend on the underlying database/provider.
+/// </remarks>
 public record DatabaseFilter : IDatabaseFilter
 {
     /// <summary>

ChatAIze.PluginApi/Databases/DatabaseSorting.cs

@@ -5,8 +5,12 @@
 namespace ChatAIze.PluginApi.Databases;
 
 /// <summary>
-/// Represents a sorting rule used to order database query results by a specified property and sort direction.
+/// Concrete <see cref="IDatabaseSorting"/> used to describe a sort order in a database query.
 /// </summary>
+/// <remarks>
+/// Use this type with database APIs that accept <see cref="IDatabaseSorting"/> (for example via <see cref="ChatAIze.Abstractions.Databases.IDatabaseManager"/>).
+/// The meaning of <see cref="Property"/> and supported fields depend on the underlying database/provider.
+/// </remarks>
 public record DatabaseSorting : IDatabaseSorting
 {
     /// <summary>