Skip to content

Commit eaa4d84

Browse files
marcel2215marcel2215
committed
Add XML docs
1 parent 8333803 commit eaa4d84

25 files changed

Lines changed: 1288 additions & 71 deletions

‎example/MyShop.cs‎

Lines changed: 68 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,24 @@
66

77
namespace ChatAIze.PluginApi.ExamplePlugin;
88

9+
/// <summary>
10+
/// A plugin loader that registers the <b>MyShop</b> plugin when the assembly is discovered.
11+
/// </summary>
12+
/// <remarks>
13+
/// The chatbot host will locate this class (because it implements <see cref="IPluginLoader"/>)
14+
/// and invoke <see cref="Load"/> to obtain the concrete <see cref="IChatbotPlugin"/> instance.
15+
/// </remarks>
916
public class MyShop : IPluginLoader
1017
{
18+
/// <summary>
19+
/// Builds and returns a configured instance of the <b>MyShop</b> plugin.
20+
/// </summary>
21+
/// <returns>The fully‑configured <see cref="IChatbotPlugin"/>.</returns>
1122
public IChatbotPlugin Load()
1223
{
24+
// ─────────────────────────────────────────────────────────────────────────────
25+
// Settings – plain scalar controls
26+
// ─────────────────────────────────────────────────────────────────────────────
1327
var setting1 = new StringSetting
1428
{
1529
Id = "myshop:name",
@@ -60,6 +74,9 @@ public IChatbotPlugin Load()
6074
DefaultValue = true
6175
};
6276

77+
// ─────────────────────────────────────────────────────────────────────────────
78+
// Settings – selection controls demonstrated with three different styles
79+
// ─────────────────────────────────────────────────────────────────────────────
6380
var setting6 = new SelectionSetting
6481
{
6582
Id = "myshop:currency",
@@ -69,9 +86,9 @@ public IChatbotPlugin Load()
6986
DefaultValue = "USD",
7087
Choices =
7188
[
72-
new SelectionChoice { Title = "US Dollar", Value = "USD" },
73-
new SelectionChoice { Title = "Euro", Value = "EUR" },
74-
new SelectionChoice { Title = "British Pound", Value = "GBP" }
89+
new SelectionChoice { Title = "US Dollar", Value = "USD" },
90+
new SelectionChoice { Title = "Euro", Value = "EUR" },
91+
new SelectionChoice { Title = "British Pound", Value = "GBP" }
7592
]
7693
};
7794

@@ -84,9 +101,9 @@ public IChatbotPlugin Load()
84101
DefaultValue = "USD",
85102
Choices =
86103
[
87-
new SelectionChoice { Title = "US Dollar", Value = "USD" },
88-
new SelectionChoice { Title = "Euro", Value = "EUR" },
89-
new SelectionChoice { Title = "British Pound", Value = "GBP" }
104+
new SelectionChoice { Title = "US Dollar", Value = "USD" },
105+
new SelectionChoice { Title = "Euro", Value = "EUR" },
106+
new SelectionChoice { Title = "British Pound", Value = "GBP" }
90107
]
91108
};
92109

@@ -99,12 +116,15 @@ public IChatbotPlugin Load()
99116
DefaultValue = "USD",
100117
Choices =
101118
[
102-
new SelectionChoice { Title = "US Dollar", Value = "USD" },
103-
new SelectionChoice { Title = "Euro", Value = "EUR" },
119+
new SelectionChoice { Title = "US Dollar", Value = "USD" },
120+
new SelectionChoice { Title = "Euro", Value = "EUR" },
104121
new SelectionChoice { Title = "British Pound", Value = "GBP" }
105122
]
106123
};
107124

125+
// ─────────────────────────────────────────────────────────────────────────────
126+
// Settings – date/time variations
127+
// ─────────────────────────────────────────────────────────────────────────────
108128
var setting9 = new DateTimeSetting
109129
{
110130
Id = "myshop:opening_hours",
@@ -121,7 +141,7 @@ public IChatbotPlugin Load()
121141
Id = "myshop:opening_hours",
122142
Title = "Opening hours",
123143
Description = "The opening hours of the shop.",
124-
Style = DateTimeSettingStyle.DateTime,
144+
Style = DateTimeSettingStyle.DateOnly,
125145
DefaultValue = DateTimeOffset.UtcNow,
126146
MinValue = DateTimeOffset.UtcNow.AddDays(-7),
127147
MaxValue = DateTimeOffset.UtcNow.AddDays(7)
@@ -147,6 +167,9 @@ public IChatbotPlugin Load()
147167
MaxItemLength = 20,
148168
};
149169

170+
// ─────────────────────────────────────────────────────────────────────────────
171+
// Miscellaneous UI elements
172+
// ─────────────────────────────────────────────────────────────────────────────
150173
var setting13 = new SettingsButton
151174
{
152175
Id = "myshop:open_store",
@@ -177,6 +200,9 @@ public IChatbotPlugin Load()
177200
MaxValueLength = 20
178201
};
179202

203+
// ─────────────────────────────────────────────────────────────────────────────
204+
// Grouping and sectioning
205+
// ─────────────────────────────────────────────────────────────────────────────
180206
var group1 = new SettingsGroup
181207
{
182208
Id = "myshop:general_settings",
@@ -209,6 +235,9 @@ public IChatbotPlugin Load()
209235
Settings = [setting10, setting11, setting12]
210236
};
211237

238+
// ─────────────────────────────────────────────────────────────────────────────
239+
// Plugin instance
240+
// ─────────────────────────────────────────────────────────────────────────────
212241
var plugin = new ChatbotPlugin
213242
{
214243
Id = new("55bc120a-b623-4d5f-91e6-ae2b9f3bf6e2"),
@@ -218,35 +247,53 @@ public IChatbotPlugin Load()
218247
SettingsCallback = _ => ValueTask.FromResult<IReadOnlyCollection<ISetting>>([section1, section2, setting13, setting14, setting15]),
219248
};
220249

250+
// ─────────────────────────────────────────────────────────────────────────────
251+
// Functions, actions, and conditions
252+
// ─────────────────────────────────────────────────────────────────────────────
221253
plugin.AddFunction(GetOrderStatus);
222254

223-
var action1 = new FunctionAction(id: "myshop:create_order", title: "Create Order", callback: () => "order created, id: 3321");
224-
_ = action1.AddStringSetting(id: "productName", title: "Product Name");
255+
var action1 = new FunctionAction(
256+
id: "myshop:create_order",
257+
title: "Create Order",
258+
callback: () => "order created, id: 3321");
259+
260+
_ = action1.AddStringSetting(
261+
id: "productName",
262+
title: "Product Name");
225263

226264
plugin.AddAction(action1);
227265

228-
var condition1 = new FunctionCondition(id: "myshop:is_domain_user", title: "Is Domain User", callback: CheckDomainUser);
266+
var condition1 = new FunctionCondition(
267+
id: "myshop:is_domain_user",
268+
title: "Is Domain User",
269+
callback: CheckDomainUser);
270+
271+
_ = condition1.AddStringSetting(
272+
id: "domain",
273+
title: "Domain",
274+
description: "The domain to check for.");
229275

230-
_ = condition1.AddStringSetting(id: "domain", title: "Domain", description: "The domain to check for.");
231276
plugin.AddCondition(condition1);
232277

233278
return plugin;
234279
}
235280

281+
/// <summary>
282+
/// Sample function that returns the status of an order.
283+
/// </summary>
236284
private static string GetOrderStatus()
237285
{
238286
return "Order status: shipped";
239287
}
240288

289+
/// <summary>
290+
/// Sample condition that allows execution only for users whose email ends with a specified domain.
291+
/// </summary>
292+
/// <param name="context">Current chat context.</param>
293+
/// <param name="domain">Domain that the user's email must match.</param>
294+
/// <returns><see langword="true"/> if the user's email ends with the specified domain; otherwise, <see langword="false"/>.</returns>
241295
private static bool CheckDomainUser(IConditionContext context, string domain)
242296
{
243-
if (context.User.Email?.EndsWith(domain, StringComparison.InvariantCultureIgnoreCase) == true)
244-
{
245-
return true;
246-
}
247-
else
248-
{
249-
return false;
250-
}
297+
return context.User.Email?.EndsWith(domain, StringComparison.InvariantCultureIgnoreCase) == true;
251298
}
252299
}

‎src/ActionResult.cs‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,22 @@
22

33
namespace ChatAIze.PluginApi;
44

5+
/// <summary>
6+
/// Represents the result of an action execution, including its identifier, outcome value, and success flag.
7+
/// </summary>
58
public record ActionResult
69
{
10+
/// <summary>
11+
/// Initializes a new instance of the <see cref="ActionResult"/> class.
12+
/// </summary>
713
public ActionResult() { }
814

15+
/// <summary>
16+
/// Initializes a new instance of the <see cref="ActionResult"/> class with the specified values.
17+
/// </summary>
18+
/// <param name="id">The identifier of the action that produced this result.</param>
19+
/// <param name="result">The output or return value from the action.</param>
20+
/// <param name="isSuccess">A flag indicating whether the action completed successfully.</param>
921
[SetsRequiredMembers]
1022
public ActionResult(string id, object result, bool isSuccess)
1123
{
@@ -14,9 +26,18 @@ public ActionResult(string id, object result, bool isSuccess)
1426
IsSuccess = isSuccess;
1527
}
1628

29+
/// <summary>
30+
/// Gets or sets the unique identifier of the action that generated this result.
31+
/// </summary>
1732
public virtual required string Id { get; set; }
1833

34+
/// <summary>
35+
/// Gets or sets the result value produced by the action.
36+
/// </summary>
1937
public virtual required object Result { get; set; }
2038

39+
/// <summary>
40+
/// Gets or sets a flag indicating whether the action completed successfully.
41+
/// </summary>
2142
public virtual bool IsSuccess { get; set; }
2243
}

‎src/ChatFunction.cs‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,24 @@
66

77
namespace ChatAIze.PluginApi;
88

9+
/// <summary>
10+
/// Represents a chatbot function implementation that includes its name, description, execution delegate, parameters, and behavioral flags.
11+
/// </summary>
912
public class ChatFunction : IChatFunction
1013
{
14+
/// <summary>
15+
/// Initializes a new instance of the <see cref="ChatFunction"/> class.
16+
/// </summary>
1117
public ChatFunction() { }
1218

19+
/// <summary>
20+
/// Initializes a new instance of the <see cref="ChatFunction"/> class using a delegate.
21+
/// </summary>
22+
/// <param name="callback">The delegate that contains the function logic.</param>
23+
/// <remarks>
24+
/// The function name is inferred from the delegate method name. If the method is decorated with a <see cref="DescriptionAttribute"/>,
25+
/// its description is used automatically.
26+
/// </remarks>
1327
[SetsRequiredMembers]
1428
public ChatFunction(Delegate callback)
1529
{
@@ -18,8 +32,21 @@ public ChatFunction(Delegate callback)
1832
Callback = callback;
1933
}
2034

35+
/// <summary>
36+
/// Initializes a new instance of the <see cref="ChatFunction"/> class with all relevant metadata.
37+
/// </summary>
38+
/// <param name="name">The unique name of the function.</param>
39+
/// <param name="description">Optional description for the function.</param>
40+
/// <param name="requiresDoubleCheck">A flag indicating whether double confirmation is required before execution.</param>
41+
/// <param name="callback">The delegate that contains the function's logic.</param>
42+
/// <param name="parameters">Optional parameters expected by the function.</param>
2143
[SetsRequiredMembers]
22-
public ChatFunction(string name, string? description = null, bool requiresDoubleCheck = false, Delegate? callback = null, params ICollection<IFunctionParameter>? parameters)
44+
public ChatFunction(
45+
string name,
46+
string? description = null,
47+
bool requiresDoubleCheck = false,
48+
Delegate? callback = null,
49+
params ICollection<IFunctionParameter>? parameters)
2350
{
2451
Name = name;
2552
Description = description;
@@ -28,15 +55,23 @@ public ChatFunction(string name, string? description = null, bool requiresDouble
2855
Parameters = parameters;
2956
}
3057

58+
/// <inheritdoc />
3159
public virtual required string Name { get; set; }
3260

61+
/// <inheritdoc />
3362
public virtual string? Description { get; set; }
3463

64+
/// <inheritdoc />
3565
public virtual bool RequiresDoubleCheck { get; set; }
3666

67+
/// <inheritdoc />
3768
public virtual Delegate? Callback { get; set; }
3869

70+
/// <summary>
71+
/// Gets or sets the list of parameters expected by this function.
72+
/// </summary>
3973
public virtual ICollection<IFunctionParameter>? Parameters { get; set; }
4074

75+
/// <inheritdoc />
4176
IReadOnlyCollection<IFunctionParameter>? IChatFunction.Parameters => (IReadOnlyCollection<IFunctionParameter>?)Parameters;
4277
}

0 commit comments

Comments
 (0)