Skip to content

Commit ce4a7c7

Browse files
CopilotCopilot
authored
Add XML documentation with see cref links to generated code for better IDE navigation (#535)
1 parent 8ae62ae commit ce4a7c7

File tree

3 files changed

+90
-0
lines changed

3 files changed

+90
-0
lines changed

‎src/Generators/DurableTaskSourceGenerator.cs‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -325,6 +325,9 @@ static void AddOrchestratorFunctionDeclaration(StringBuilder sourceBuilder, Dura
325325
static void AddOrchestratorCallMethod(StringBuilder sourceBuilder, DurableTaskTypeInfo orchestrator)
326326
{
327327
sourceBuilder.AppendLine($@"
328+
/// <summary>
329+
/// Schedules a new instance of the <see cref=""{orchestrator.TypeName}""/> orchestrator.
330+
/// </summary>
328331
/// <inheritdoc cref=""IOrchestrationSubmitter.ScheduleNewOrchestrationInstanceAsync""/>
329332
public static Task<string> ScheduleNew{orchestrator.TaskName}InstanceAsync(
330333
this IOrchestrationSubmitter client, {orchestrator.InputParameter}, StartOrchestrationOptions? options = null)
@@ -336,6 +339,9 @@ static void AddOrchestratorCallMethod(StringBuilder sourceBuilder, DurableTaskTy
336339
static void AddSubOrchestratorCallMethod(StringBuilder sourceBuilder, DurableTaskTypeInfo orchestrator)
337340
{
338341
sourceBuilder.AppendLine($@"
342+
/// <summary>
343+
/// Calls the <see cref=""{orchestrator.TypeName}""/> sub-orchestrator.
344+
/// </summary>
339345
/// <inheritdoc cref=""TaskOrchestrationContext.CallSubOrchestratorAsync(TaskName, object?, TaskOptions?)""/>
340346
public static Task<{orchestrator.OutputType}> Call{orchestrator.TaskName}Async(
341347
this TaskOrchestrationContext context, {orchestrator.InputParameter}, TaskOptions? options = null)
@@ -347,6 +353,10 @@ static void AddSubOrchestratorCallMethod(StringBuilder sourceBuilder, DurableTas
347353
static void AddActivityCallMethod(StringBuilder sourceBuilder, DurableTaskTypeInfo activity)
348354
{
349355
sourceBuilder.AppendLine($@"
356+
/// <summary>
357+
/// Calls the <see cref=""{activity.TypeName}""/> activity.
358+
/// </summary>
359+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
350360
public static Task<{activity.OutputType}> Call{activity.TaskName}Async(this TaskOrchestrationContext ctx, {activity.InputParameter}, TaskOptions? options = null)
351361
{{
352362
return ctx.CallActivityAsync<{activity.OutputType}>(""{activity.TaskName}"", input, options);
@@ -356,6 +366,10 @@ static void AddActivityCallMethod(StringBuilder sourceBuilder, DurableTaskTypeIn
356366
static void AddActivityCallMethod(StringBuilder sourceBuilder, DurableFunction activity)
357367
{
358368
sourceBuilder.AppendLine($@"
369+
/// <summary>
370+
/// Calls the <see cref=""{activity.FullTypeName}""/> activity.
371+
/// </summary>
372+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
359373
public static Task<{activity.ReturnType}> Call{activity.Name}Async(this TaskOrchestrationContext ctx, {activity.Parameter}, TaskOptions? options = null)
360374
{{
361375
return ctx.CallActivityAsync<{activity.ReturnType}>(""{activity.Name}"", {activity.Parameter.Name}, options);

‎test/Generators.Tests/AzureFunctionsTests.cs‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,10 @@ public class Calculator
2727
string expectedOutput = TestHelpers.WrapAndFormat(
2828
GeneratedClassName,
2929
methodList: @"
30+
/// <summary>
31+
/// Calls the <see cref=""Calculator.Identity""/> activity.
32+
/// </summary>
33+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
3034
public static Task<int> CallIdentityAsync(this TaskOrchestrationContext ctx, int input, TaskOptions? options = null)
3135
{
3236
return ctx.CallActivityAsync<int>(""Identity"", input, options);
@@ -57,6 +61,10 @@ public class Calculator
5761
string expectedOutput = TestHelpers.WrapAndFormat(
5862
GeneratedClassName,
5963
methodList: @"
64+
/// <summary>
65+
/// Calls the <see cref=""Calculator.IdentityAsync""/> activity.
66+
/// </summary>
67+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
6068
public static Task<int> CallIdentityAsync(this TaskOrchestrationContext ctx, int input, TaskOptions? options = null)
6169
{
6270
return ctx.CallActivityAsync<int>(""Identity"", input, options);
@@ -92,6 +100,10 @@ public class Calculator
92100
string expectedOutput = TestHelpers.WrapAndFormat(
93101
GeneratedClassName,
94102
methodList: @"
103+
/// <summary>
104+
/// Calls the <see cref=""AzureFunctionsTests.Calculator.Identity""/> activity.
105+
/// </summary>
106+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
95107
public static Task<AzureFunctionsTests.Input> CallIdentityAsync(this TaskOrchestrationContext ctx, AzureFunctionsTests.Input input, TaskOptions? options = null)
96108
{
97109
return ctx.CallActivityAsync<AzureFunctionsTests.Input>(""Identity"", input, options);
@@ -141,6 +153,10 @@ public class MyActivity : TaskActivity<{inputType}, {outputType}>
141153
string expectedOutput = TestHelpers.WrapAndFormat(
142154
GeneratedClassName,
143155
methodList: $@"
156+
/// <summary>
157+
/// Calls the <see cref=""MyActivity""/> activity.
158+
/// </summary>
159+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
144160
public static Task<{outputType}> CallMyActivityAsync(this TaskOrchestrationContext ctx, {inputType} input, TaskOptions? options = null)
145161
{{
146162
return ctx.CallActivityAsync<{outputType}>(""MyActivity"", input, options);
@@ -214,13 +230,19 @@ public class MyOrchestrator : TaskOrchestrator<{inputType}, {outputType}>
214230
.ContinueWith(t => ({outputType})(t.Result ?? default({outputType})!), TaskContinuationOptions.ExecuteSynchronously);
215231
}}
216232
233+
/// <summary>
234+
/// Schedules a new instance of the <see cref=""MyNS.MyOrchestrator""/> orchestrator.
235+
/// </summary>
217236
/// <inheritdoc cref=""IOrchestrationSubmitter.ScheduleNewOrchestrationInstanceAsync""/>
218237
public static Task<string> ScheduleNewMyOrchestratorInstanceAsync(
219238
this IOrchestrationSubmitter client, {expectedInputParameter}, StartOrchestrationOptions? options = null)
220239
{{
221240
return client.ScheduleNewOrchestrationInstanceAsync(""MyOrchestrator"", input, options);
222241
}}
223242
243+
/// <summary>
244+
/// Calls the <see cref=""MyNS.MyOrchestrator""/> sub-orchestrator.
245+
/// </summary>
224246
/// <inheritdoc cref=""TaskOrchestrationContext.CallSubOrchestratorAsync(TaskName, object?, TaskOptions?)""/>
225247
public static Task<{outputType}> CallMyOrchestratorAsync(
226248
this TaskOrchestrationContext context, {expectedInputParameter}, TaskOptions? options = null)
@@ -291,13 +313,19 @@ public abstract class MyOrchestratorBase : TaskOrchestrator<{inputType}, {output
291313
.ContinueWith(t => ({outputType})(t.Result ?? default({outputType})!), TaskContinuationOptions.ExecuteSynchronously);
292314
}}
293315
316+
/// <summary>
317+
/// Schedules a new instance of the <see cref=""MyNS.MyOrchestrator""/> orchestrator.
318+
/// </summary>
294319
/// <inheritdoc cref=""IOrchestrationSubmitter.ScheduleNewOrchestrationInstanceAsync""/>
295320
public static Task<string> ScheduleNewMyOrchestratorInstanceAsync(
296321
this IOrchestrationSubmitter client, {expectedInputParameter}, StartOrchestrationOptions? options = null)
297322
{{
298323
return client.ScheduleNewOrchestrationInstanceAsync(""MyOrchestrator"", input, options);
299324
}}
300325
326+
/// <summary>
327+
/// Calls the <see cref=""MyNS.MyOrchestrator""/> sub-orchestrator.
328+
/// </summary>
301329
/// <inheritdoc cref=""TaskOrchestrationContext.CallSubOrchestratorAsync(TaskName, object?, TaskOptions?)""/>
302330
public static Task<{outputType}> CallMyOrchestratorAsync(
303331
this TaskOrchestrationContext context, {expectedInputParameter}, TaskOptions? options = null)
@@ -493,20 +521,30 @@ public static Task<string> MyOrchestrator([OrchestrationTrigger] TaskOrchestrati
493521
.ContinueWith(t => (string)(t.Result ?? default(string)!), TaskContinuationOptions.ExecuteSynchronously);
494522
}}
495523
524+
/// <summary>
525+
/// Schedules a new instance of the <see cref=""MyNS.MyOrchestrator""/> orchestrator.
526+
/// </summary>
496527
/// <inheritdoc cref=""IOrchestrationSubmitter.ScheduleNewOrchestrationInstanceAsync""/>
497528
public static Task<string> ScheduleNewMyOrchestratorInstanceAsync(
498529
this IOrchestrationSubmitter client, int input, StartOrchestrationOptions? options = null)
499530
{{
500531
return client.ScheduleNewOrchestrationInstanceAsync(""MyOrchestrator"", input, options);
501532
}}
502533
534+
/// <summary>
535+
/// Calls the <see cref=""MyNS.MyOrchestrator""/> sub-orchestrator.
536+
/// </summary>
503537
/// <inheritdoc cref=""TaskOrchestrationContext.CallSubOrchestratorAsync(TaskName, object?, TaskOptions?)""/>
504538
public static Task<string> CallMyOrchestratorAsync(
505539
this TaskOrchestrationContext context, int input, TaskOptions? options = null)
506540
{{
507541
return context.CallSubOrchestratorAsync<string>(""MyOrchestrator"", input, options);
508542
}}
509543
544+
/// <summary>
545+
/// Calls the <see cref=""MyNS.MyActivity""/> activity.
546+
/// </summary>
547+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
510548
public static Task<string> CallMyActivityAsync(this TaskOrchestrationContext ctx, int input, TaskOptions? options = null)
511549
{{
512550
return ctx.CallActivityAsync<string>(""MyActivity"", input, options);

‎test/Generators.Tests/ClassBasedSyntaxTests.cs‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,13 +31,19 @@ class MyOrchestrator : TaskOrchestrator<{type}, string>
3131
string expectedOutput = TestHelpers.WrapAndFormat(
3232
GeneratedClassName,
3333
methodList: $@"
34+
/// <summary>
35+
/// Schedules a new instance of the <see cref=""MyOrchestrator""/> orchestrator.
36+
/// </summary>
3437
/// <inheritdoc cref=""IOrchestrationSubmitter.ScheduleNewOrchestrationInstanceAsync""/>
3538
public static Task<string> ScheduleNewMyOrchestratorInstanceAsync(
3639
this IOrchestrationSubmitter client, {input}, StartOrchestrationOptions? options = null)
3740
{{
3841
return client.ScheduleNewOrchestrationInstanceAsync(""MyOrchestrator"", input, options);
3942
}}
4043
44+
/// <summary>
45+
/// Calls the <see cref=""MyOrchestrator""/> sub-orchestrator.
46+
/// </summary>
4147
/// <inheritdoc cref=""TaskOrchestrationContext.CallSubOrchestratorAsync(TaskName, object?, TaskOptions?)""/>
4248
public static Task<string> CallMyOrchestratorAsync(
4349
this TaskOrchestrationContext context, {input}, TaskOptions? options = null)
@@ -80,13 +86,19 @@ abstract class MyOrchestratorBase : TaskOrchestrator<int, string>
8086
string expectedOutput = TestHelpers.WrapAndFormat(
8187
GeneratedClassName,
8288
methodList: @"
89+
/// <summary>
90+
/// Schedules a new instance of the <see cref=""MyOrchestrator""/> orchestrator.
91+
/// </summary>
8392
/// <inheritdoc cref=""IOrchestrationSubmitter.ScheduleNewOrchestrationInstanceAsync""/>
8493
public static Task<string> ScheduleNewMyOrchestratorInstanceAsync(
8594
this IOrchestrationSubmitter client, int input, StartOrchestrationOptions? options = null)
8695
{
8796
return client.ScheduleNewOrchestrationInstanceAsync(""MyOrchestrator"", input, options);
8897
}
8998
99+
/// <summary>
100+
/// Calls the <see cref=""MyOrchestrator""/> sub-orchestrator.
101+
/// </summary>
90102
/// <inheritdoc cref=""TaskOrchestrationContext.CallSubOrchestratorAsync(TaskName, object?, TaskOptions?)""/>
91103
public static Task<string> CallMyOrchestratorAsync(
92104
this TaskOrchestrationContext context, int input, TaskOptions? options = null)
@@ -129,6 +141,10 @@ class MyActivity : TaskActivity<{type}, string>
129141
string expectedOutput = TestHelpers.WrapAndFormat(
130142
GeneratedClassName,
131143
methodList: $@"
144+
/// <summary>
145+
/// Calls the <see cref=""MyActivity""/> activity.
146+
/// </summary>
147+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
132148
public static Task<string> CallMyActivityAsync(this TaskOrchestrationContext ctx, {input}, TaskOptions? options = null)
133149
{{
134150
return ctx.CallActivityAsync<string>(""MyActivity"", input, options);
@@ -169,6 +185,10 @@ public class MyClass { }
169185
string expectedOutput = TestHelpers.WrapAndFormat(
170186
generatedClassName: "GeneratedDurableTaskExtensions",
171187
methodList: @"
188+
/// <summary>
189+
/// Calls the <see cref=""MyActivity""/> activity.
190+
/// </summary>
191+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
172192
public static Task<MyNS.MyClass> CallMyActivityAsync(this TaskOrchestrationContext ctx, MyNS.MyClass input, TaskOptions? options = null)
173193
{
174194
return ctx.CallActivityAsync<MyNS.MyClass>(""MyActivity"", input, options);
@@ -211,6 +231,10 @@ public class MyClass { }
211231
string expectedOutput = TestHelpers.WrapAndFormat(
212232
GeneratedClassName,
213233
methodList: @"
234+
/// <summary>
235+
/// Calls the <see cref=""MyNS.MyActivityImpl""/> activity.
236+
/// </summary>
237+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
214238
public static Task<MyNS.MyClass> CallMyActivityAsync(this TaskOrchestrationContext ctx, MyNS.MyClass input, TaskOptions? options = null)
215239
{
216240
return ctx.CallActivityAsync<MyNS.MyClass>(""MyActivity"", input, options);
@@ -250,6 +274,10 @@ abstract class MyActivityBase : TaskActivity<int, string>
250274
string expectedOutput = TestHelpers.WrapAndFormat(
251275
GeneratedClassName,
252276
methodList: @"
277+
/// <summary>
278+
/// Calls the <see cref=""MyActivity""/> activity.
279+
/// </summary>
280+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
253281
public static Task<string> CallMyActivityAsync(this TaskOrchestrationContext ctx, int input, TaskOptions? options = null)
254282
{
255283
return ctx.CallActivityAsync<string>(""MyActivity"", input, options);
@@ -440,20 +468,30 @@ class MyEntity : TaskEntity<int>
440468
string expectedOutput = TestHelpers.WrapAndFormat(
441469
GeneratedClassName,
442470
methodList: @"
471+
/// <summary>
472+
/// Schedules a new instance of the <see cref=""MyOrchestrator""/> orchestrator.
473+
/// </summary>
443474
/// <inheritdoc cref=""IOrchestrationSubmitter.ScheduleNewOrchestrationInstanceAsync""/>
444475
public static Task<string> ScheduleNewMyOrchestratorInstanceAsync(
445476
this IOrchestrationSubmitter client, int input, StartOrchestrationOptions? options = null)
446477
{
447478
return client.ScheduleNewOrchestrationInstanceAsync(""MyOrchestrator"", input, options);
448479
}
449480
481+
/// <summary>
482+
/// Calls the <see cref=""MyOrchestrator""/> sub-orchestrator.
483+
/// </summary>
450484
/// <inheritdoc cref=""TaskOrchestrationContext.CallSubOrchestratorAsync(TaskName, object?, TaskOptions?)""/>
451485
public static Task<string> CallMyOrchestratorAsync(
452486
this TaskOrchestrationContext context, int input, TaskOptions? options = null)
453487
{
454488
return context.CallSubOrchestratorAsync<string>(""MyOrchestrator"", input, options);
455489
}
456490
491+
/// <summary>
492+
/// Calls the <see cref=""MyActivity""/> activity.
493+
/// </summary>
494+
/// <inheritdoc cref=""TaskOrchestrationContext.CallActivityAsync(TaskName, object?, TaskOptions?)""/>
457495
public static Task<string> CallMyActivityAsync(this TaskOrchestrationContext ctx, int input, TaskOptions? options = null)
458496
{
459497
return ctx.CallActivityAsync<string>(""MyActivity"", input, options);

0 commit comments

Comments
 (0)