Refactor: Enhance interface generation examples to improve clarity and align with domain-specific use cases

Author: NikolayPianikov

.run/Test examples with name.run.xml

@@ -0,0 +1,23 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Test examples with name" type="DotNetProject" factoryName=".NET Project" folderName="Targets">
+    <option name="EXE_PATH" value="$PROJECT_DIR$/build/bin/Debug/net10.0/build.exe" />
+    <option name="PROGRAM_PARAMETERS" value="&quot;-p:example=Customize the generated interface&quot; -- te" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="PASS_PARENT_ENVS" value="1" />
+    <option name="ENV_FILE_PATHS" value="" />
+    <option name="REDIRECT_INPUT_PATH" value="" />
+    <option name="MIXED_MODE_DEBUG" value="0" />
+    <option name="USE_MONO" value="0" />
+    <option name="RUNTIME_ARGUMENTS" value="" />
+    <option name="AUTO_ATTACH_CHILDREN" value="0" />
+    <option name="PROJECT_PATH" value="$PROJECT_DIR$/build/build.csproj" />
+    <option name="PROJECT_EXE_PATH_TRACKING" value="1" />
+    <option name="PROJECT_ARGUMENTS_TRACKING" value="1" />
+    <option name="PROJECT_WORKING_DIRECTORY_TRACKING" value="0" />
+    <option name="PROJECT_KIND" value="DotNetCore" />
+    <option name="PROJECT_TFM" value="net10.0" />
+    <method v="2">
+      <option name="Build" />
+    </method>
+  </configuration>
+</component>

build/Core/Targets/CreateExamplesTarget.cs

@@ -28,6 +28,7 @@ class CreateExamplesTarget(
         "Attributes",
         "Interception",
         "Hints",
+        "Interfaces",
         "Advanced",
         "UseCases",
         "Unity"

build/Core/Targets/TestExamplesTarget.cs

@@ -7,6 +7,7 @@ namespace Build.Core.Targets;
 class TestExamplesTarget(
     Commands commands,
     Env env,
+    Properties properties,
     [Tag(typeof(CreateExamplesTarget))] ITarget<IReadOnlyCollection<ExampleGroup>> createExamplesTarget)
     : IInitializable, ITarget<int>
 {
@@ -31,6 +32,7 @@ public async Task<int> RunAsync(CancellationToken cancellationToken)
             var appDir = Path.Combine(tempDir, "App");
             File.Copy(Path.Combine(solutionDir, "tests", "Pure.DI.UsageTests", "Test.props"), Path.Combine(appDir, "Directory.Build.props"));
             var programFile = Path.Combine(appDir, "Program.cs");
+            var example = properties["example"];
             foreach (var (_, groupExamples) in examples)
             {
                 foreach (var vars in groupExamples)
@@ -41,6 +43,12 @@ public async Task<int> RunAsync(CancellationToken cancellationToken)
                     }
 
                     var description = vars[CreateExamplesTarget.DescriptionKey];
+                    if (!string.IsNullOrWhiteSpace(example)
+                        && !string.Equals(example, description, StringComparison.InvariantCultureIgnoreCase))
+                    {
+                        continue;
+                    }
+
                     var code = vars[CreateExamplesTarget.BodyKey];
                     await File.WriteAllTextAsync(programFile, code, cancellationToken);
                     var result = new DotNetBuild()

tests/Pure.DI.UsageTests/Interface/GenerateInterfaceGenericTypeScenario.cs

@@ -2,12 +2,12 @@
 $v=true
 $p=9
 $d=Customize the generated interface
-$h=This example shows how to change the generated interface name, namespace, and accessibility.
+$h=This example shows how to place a generated contract in a dedicated Contracts namespace.
 $f=The example shows how to:
 $f=- Generate an interface into a custom namespace
 $f=- Rename the generated interface
-$f=- Make the generated interface internal
-$r=Shouldly
+$f=- Keep the contract separate from implementation details
+$i=false
 */
 
 // ReSharper disable ClassNeverInstantiated.Global
@@ -17,23 +17,9 @@
 
 using Pure.DI;
 
-namespace Contracts
-{
-    public partial interface IWorker;
-
-    [GenerateInterface(namespaceName: "Contracts", interfaceName: "IWorker")]
-    public class Worker : IWorker
-    {
-        public string Message => "custom";
-    }
-}
-
-namespace Pure.DI.UsageTests.Interface.GenerateInterfaceCustomizationScenario
+namespace Pure.DI.UsageTests.Interfaces.GenerateInterfaceCustomizationScenario
 {
-    using Pure.DI.UsageTests;
     using Contracts;
-    using Pure.DI;
-    using Shouldly;
     using Xunit;
 
     // {
@@ -47,21 +33,36 @@ public void Run()
         {
             // {
             DI.Setup(nameof(Composition))
-                .Bind().To<Worker>()
+                .Bind<IInvoiceGenerator>().To<InvoiceGenerator>()
                 .Root<App>(nameof(App));
 
             var composition = new Composition();
             var app = composition.App;
 
-            app.Message.ShouldBe("custom");
+            app.InvoiceId.ShouldBe("INV-0042");
             // }
 
             composition.SaveClassDiagram();
         }
     }
 
-    public class App(IWorker worker)
+    // {
+    public class App(IInvoiceGenerator generator)
+    {
+        public string InvoiceId { get; } = generator.Format(42);
+    }
+    // }
+}
+
+// {
+namespace Contracts
+{
+    public partial interface IInvoiceGenerator;
+
+    [GenerateInterface(namespaceName: "Contracts", interfaceName: "IInvoiceGenerator")]
+    public class InvoiceGenerator : IInvoiceGenerator
     {
-        public string Message { get; } = worker.Message;
+        public string Format(int number) => $"INV-{number:0000}";
     }
 }
+// }

…enerateInterfaceCustomizationScenario.cs …enerateInterfaceCustomizationScenario.cstests/Pure.DI.UsageTests/Interface/GenerateInterfaceCustomizationScenario.cs renamed to tests/Pure.DI.UsageTests/Interfaces/GenerateInterfaceCustomizationScenario.cs tests/Pure.DI.UsageTests/Interface/GenerateInterfaceCustomizationScenario.cs renamed to tests/Pure.DI.UsageTests/Interfaces/GenerateInterfaceCustomizationScenario.cs

@@ -2,7 +2,7 @@
 $v=true
 $p=9
 $d=Generate interfaces with generics
-$h=This example shows that generic members, nullable annotations, and events are preserved in the generated interface.
+$h=This example shows how generic members, nullable annotations, and events are preserved in a reporting scenario.
 $f=The example shows how to:
 $f=- Generate an interface for generic members
 $f=- Preserve nullable annotations
@@ -15,12 +15,9 @@
 // ReSharper disable UnusedType.Global
 // ReSharper disable UnusedMember.Global
 
-namespace Pure.DI.UsageTests.Interface.GenerateInterfaceGenericsScenario;
+#pragma warning disable CS0067
+namespace Pure.DI.UsageTests.Interfaces.GenerateInterfaceGenericsScenario;
 
-using System;
-using Pure.DI.UsageTests;
-using Pure.DI;
-using Shouldly;
 using Xunit;
 
 // {
@@ -34,32 +31,29 @@ public void Run()
     {
         // {
         DI.Setup(nameof(Composition))
-            .Bind().To<Formatter>()
-            .Bind<App>().To<App>()
+            .Bind<IReportFormatter>().To<ReportFormatter>()
             .Root<App>(nameof(App));
 
         var composition = new Composition();
         var app = composition.App;
 
-        app.Formatted.ShouldBe("demo");
-        app.Title.ShouldBe("demo");
+        app.Formatted.ShouldBe("Order #42");
+        app.Title.ShouldBe("Daily Report");
         // }
 
         composition.SaveClassDiagram();
     }
 }
 
 // {
-public partial interface IFormatter;
+public partial interface IReportFormatter;
 
 [GenerateInterface]
-public class Formatter : IFormatter
+public class ReportFormatter : IReportFormatter
 {
-    public string? Title { get; set; } = "demo";
+    public string? Title { get; set; } = "Daily Report";
 
-#pragma warning disable CS0067
     public event EventHandler? Changed;
-#pragma warning restore CS0067
 
     public string? Format<T>(T value)
         where T : class
@@ -69,10 +63,15 @@ public class Formatter : IFormatter
     public void Hidden() { }
 }
 
-public class App(IFormatter formatter)
+public class App(IReportFormatter formatter)
 {
     public string Title { get; } = formatter.Title ?? string.Empty;
 
-    public string Formatted { get; } = formatter.Format("demo") ?? string.Empty;
+    public string Formatted { get; } = formatter.Format(new Order(42)) ?? string.Empty;
+}
+
+public class Order(int id)
+{
+    public override string ToString() => $"Order #{id}";
 }
 // }

…ace/GenerateInterfaceGenericsScenario.cs …ces/GenerateInterfaceGenericsScenario.cstests/Pure.DI.UsageTests/Interface/GenerateInterfaceGenericsScenario.cs renamed to tests/Pure.DI.UsageTests/Interfaces/GenerateInterfaceGenericsScenario.cs tests/Pure.DI.UsageTests/Interface/GenerateInterfaceGenericsScenario.cs renamed to tests/Pure.DI.UsageTests/Interfaces/GenerateInterfaceGenericsScenario.cs

@@ -2,11 +2,11 @@
 $v=true
 $p=9
 $d=Generate an interface from a class
-$h=This example shows how a public class can generate a matching interface and be used through Pure.DI.
+$h=This example shows how a concrete service can generate a matching interface and be consumed through Pure.DI.
 $f=The example shows how to:
 $f=- Generate an interface from a class
 $f=- Bind the generated contract in Pure.DI
-$f=- Resolve the consumer from a composition root
+$f=- Resolve a consumer that depends on the interface
 $r=Shouldly
 */
 
@@ -15,11 +15,8 @@
 // ReSharper disable UnusedType.Global
 // ReSharper disable UnusedMember.Global
 
-namespace Pure.DI.UsageTests.Interface.GenerateInterfaceScenario;
+namespace Pure.DI.UsageTests.Interfaces.GenerateInterfaceScenario;
 
-using Pure.DI.UsageTests;
-using Pure.DI;
-using Shouldly;
 using Xunit;
 
 // {
@@ -33,35 +30,35 @@ public void Run()
     {
         // {
         DI.Setup(nameof(Composition))
-            .Bind().To<Service>()
+            .Bind().To<EmailSender>()
             .Root<App>(nameof(App));
 
         var composition = new Composition();
         var app = composition.App;
 
-        app.Message.ShouldBe("ok");
-        app.Text.ShouldBe("pong");
+        app.Provider.ShouldBe("smtp");
+        app.Result.ShouldBe("sent:ops@contoso.com");
         // }
 
         composition.SaveClassDiagram();
     }
 }
 
 // {
-public partial interface IService;
+public partial interface IEmailSender;
 
 [GenerateInterface]
-public class Service : IService
+public class EmailSender : IEmailSender
 {
-    public string Message => "ok";
+    public string Provider => "smtp";
 
-    public string Ping() => "pong";
+    public string Send(string address) => $"sent:{address}";
 }
 
-public class App(IService service)
+public class App(IEmailSender sender)
 {
-    public string Message { get; } = service.Message;
+    public string Provider { get; } = sender.Provider;
 
-    public string Text { get; } = service.Ping();
+    public string Result { get; } = sender.Send("ops@contoso.com");
 }
 // }