Enhance generated comments for roots, constructors, and Dispose methods with detailed descriptions. Add debugging and API reference guides to documentation. Improve Resolve/ResolveByTag behavior clarifications when handling root arguments.

Author: Nikolay Pianikov

.gitignore

@@ -5,6 +5,7 @@
 **/*.DotSettings.user
 **/*.csproj.user
 **/*.log
+/tests/Pure.DI.GeneratedCodeReview/Generated
 benchmarks/data/*.log
 benchmarks/data/results/*.md
 *.suo
@@ -24,4 +25,3 @@ _ReSharper.Caches/
 /samples/UnityApp/*.csproj
 /samples/UnityApp/*.sln
 /samples/UnityApp/*.slnx
-

Pure.DI.sln

@@ -127,6 +127,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "EF", "samples\EF\EF.csproj"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "HugeComposition", "samples\HugeComposition\HugeComposition.csproj", "{E1B0FCD1-B34B-4707-A2A2-276D30FC5593}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Pure.DI.GeneratedCodeReview", "tests\Pure.DI.GeneratedCodeReview\Pure.DI.GeneratedCodeReview.csproj", "{C31B21FA-0339-4184-8A22-BD4B8A78730A}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -257,6 +259,10 @@ Global
 		{E1B0FCD1-B34B-4707-A2A2-276D30FC5593}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{E1B0FCD1-B34B-4707-A2A2-276D30FC5593}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{E1B0FCD1-B34B-4707-A2A2-276D30FC5593}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C31B21FA-0339-4184-8A22-BD4B8A78730A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C31B21FA-0339-4184-8A22-BD4B8A78730A}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C31B21FA-0339-4184-8A22-BD4B8A78730A}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C31B21FA-0339-4184-8A22-BD4B8A78730A}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{7C9E056B-CBA9-4548-9CDB-C5CE03C491B0} = {8163CDD7-7018-4301-A984-803C3807A6A6}
@@ -289,5 +295,6 @@ Global
 		{006A6849-86DC-43C7-8297-67249A807439} = {FA80D231-C641-4A49-99C6-0C065D818B07}
 		{658990AA-FA40-4B28-8E14-2AB8BBD9C701} = {FA80D231-C641-4A49-99C6-0C065D818B07}
 		{E1B0FCD1-B34B-4707-A2A2-276D30FC5593} = {FA80D231-C641-4A49-99C6-0C065D818B07}
+		{C31B21FA-0339-4184-8A22-BD4B8A78730A} = {9DF1D09E-863F-4800-9E28-954440EE1601}
 	EndGlobalSection
 EndGlobal

readme/FooterTemplate.md

@@ -58,6 +58,78 @@ The _compositionTypeName_ parameter can be omitted:
 
 </details>
 
+<details>
+<summary>How to read generated code</summary>
+
+Generated code is regular C# code. Read it in two passes:
+
+1. First inspect the generated public API of the composition.
+2. Then inspect implementation details only when debugging lifetimes, scopes, or performance.
+
+The public API answers the main questions:
+
+- Which composition class was generated from `DI.Setup(...)`.
+- Which roots are available as properties or methods.
+- Which constructor arguments are required by the composition.
+- Whether `Resolve`/`ResolveByTag` methods, scopes, `Dispose`, or `DisposeAsync` were generated.
+
+For example, this setup:
+
+```c#
+DI.Setup("Composition")
+    .Arg<string>("connectionString")
+    .RootArg<Guid>("userId")
+    .Bind<IRepository>().To<Repository>()
+    .Bind<IService>().To<Service>()
+    .Root<IService>("CreateService");
+```
+
+produces a composition API shaped like this:
+
+```c#
+partial class Composition
+{
+    public Composition(string connectionString) { ... }
+
+    public IService CreateService(Guid userId) { ... }
+}
+```
+
+The implementation body shows how Pure.DI creates the graph:
+
+- `new Implementation(...)` calls show constructor injection.
+- Private fields usually represent cached singleton or scoped instances.
+- Lock statements appear when thread-safe access is required.
+- Local variables named for per-resolve or per-block lifetimes show reuse inside one generated root body.
+- `Dispose` and `DisposeAsync` release tracked singleton and scoped disposable instances.
+
+Use `Hint.FormatCode` only when reading or presenting generated code. It can increase compilation time and memory usage.
+
+</details>
+
+<details>
+<summary>Generated API reference</summary>
+
+| Setup element                          | Generated API                                                                                                                         |
+|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
+| `DI.Setup("Composition")`              | A partial class named `Composition`, unless the setup kind prevents class generation.                                                 |
+| `.Root<T>("Name")`                     | A public property named `Name`, or a method named `Name` when the root uses root arguments or generic type arguments.                 |
+| `.Root<T>()`                           | An anonymous private root. It is available only through generated `Resolve`/`ResolveByTag` methods when those methods can resolve it. |
+| `.Arg<T>("name")`                      | A composition constructor parameter when the argument is used by at least one root graph.                                             |
+| `.RootArg<T>("name")`                  | A parameter on root methods that use this value. Roots with root arguments cannot be resolved by `Resolve`/`ResolveByTag`.            |
+| `Lifetime.Transient`                   | A new instance is created at each injection site.                                                                                     |
+| `Lifetime.Singleton`                   | A private cached field is generated and reused by the composition.                                                                    |
+| `Lifetime.Scoped`                      | Scope-related constructors/members are generated and the instance is reused inside a scope.                                           |
+| `Lifetime.PerResolve`                  | A local value is reused during one root or `Resolve` call.                                                                            |
+| `Lifetime.PerBlock`                    | A local value is reused inside a generated code block.                                                                                |
+| Disposable singleton/scoped dependency | `Dispose` and/or `DisposeAsync` are generated on the composition.                                                                     |
+| `Hint.Resolve = Off`                   | `Resolve`/`ResolveByTag` methods and anonymous roots are not generated. Use named roots directly.                                     |
+| `Hint.ToString = On`                   | `ToString()` returns a Mermaid class diagram of the composition.                                                                      |
+| `Hint.Comments = Off`                  | XML documentation comments are not generated for the composition API.                                                                 |
+| `Hint.FormatCode = On`                 | Generated code is formatted for easier reading.                                                                                       |
+
+</details>
+
 <details>
 <summary>Setup arguments</summary>
 
@@ -1523,6 +1595,17 @@ See also:
 <summary>Comments</summary>
 
 Pure.DI can copy comments from setup calls into generated documentation comments for the composition class, composition arguments, and composition roots.
+When no user comment is provided, Pure.DI generates documentation for the generated API so the composition can be inspected from IntelliSense.
+
+Generated comments describe:
+
+- The composition roots exposed by the generated composition class.
+- The root contract, implementation type, tag, and lifetime.
+- Whether a root is a property or a method.
+- Composition constructor parameters created from used `Arg<T>(...)` values.
+- Root method parameters created from used `RootArg<T>(...)` values.
+- `Resolve`/`ResolveByTag` limitations for roots that require root arguments.
+- `Dispose`/`DisposeAsync` behavior for tracked singleton and scoped disposable instances.
 
 Use regular `//` comments before API calls when you want Pure.DI to include the text in the generated documentation:
 
@@ -1561,6 +1644,15 @@ public IService Service
 
 For other setup calls, such as `Arg<T>(...)`, comments are used as documentation text in the generated constructor documentation. Use regular `//` comments there unless you want XML markup to be shown as text.
 
+To suppress generated documentation comments, turn comments off for the setup:
+
+```c#
+DI.Setup("Composition")
+    .Hint(Hint.Comments, "Off")
+    .Bind<IService>().To<Service>()
+    .Root<IService>("Service");
+```
+
 </details>
 
 <details>
@@ -1599,6 +1691,65 @@ flowchart TD
 
 </details>
 
+<details>
+<summary>Debugging generated code</summary>
+
+Use this workflow when you need to inspect or debug the generated composition:
+
+1. Save generated files in the project.
+
+```xml
+<PropertyGroup>
+    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
+    <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)Generated</CompilerGeneratedFilesOutputPath>
+</PropertyGroup>
+```
+
+2. Enable formatting only while debugging.
+
+```c#
+DI.Setup("Composition")
+    .Hint(Hint.FormatCode, "On")
+    .Bind<IService>().To<Service>()
+    .Root<IService>("Service");
+```
+
+3. Rebuild the project and open the generated `Composition.g.cs` file under the configured generated files folder.
+
+4. Start with the generated public API:
+
+- composition constructors;
+- root properties and root methods;
+- `Resolve`/`ResolveByTag` methods;
+- scope factory methods;
+- `Dispose`/`DisposeAsync`.
+
+5. Then inspect the root body that creates the graph. Constructor calls show the exact dependency path, private fields show cached singleton/scoped values, and local variables show per-resolve/per-block reuse.
+
+6. For a structural view, enable `Hint.ToString` and render the Mermaid diagram:
+
+```c#
+DI.Setup("Composition")
+    .Hint(Hint.ToString, "On")
+    .Bind<IService>().To<Service>()
+    .Root<IService>("Service");
+
+var diagram = new Composition().ToString();
+```
+
+7. If an anonymous root is hard to step through, disable lightweight anonymous roots for debugging:
+
+```c#
+DI.Setup("Composition")
+    .Hint(Hint.LightweightAnonymousRoot, "Off")
+    .Bind<IService>().To<Service>()
+    .Root<IService>();
+```
+
+Turn `FormatCode`, `ToString`, and extra debugging hints off again when they are no longer needed.
+
+</details>
+
 ## Project template
 
 Install the DI template [Pure.DI.Templates](https://www.nuget.org/packages/Pure.DI.Templates)
@@ -1676,6 +1827,62 @@ You can set project properties to save generated files and control their storage
 
 </details>
 
+<details>
+<summary>Generated code troubleshooting</summary>
+
+### Generated files are not visible
+
+Set `EmitCompilerGeneratedFiles` to `true`, rebuild the project, and check the generated files folder configured by `CompilerGeneratedFilesOutputPath`. If the folder is empty, run `dotnet build-server shutdown`, rebuild, and check that the project references the `Pure.DI` package.
+
+### The root was generated as a method, not a property
+
+A root becomes a method when it needs runtime data, such as `RootArg<T>(...)`, or when the root itself is generic. Call it directly and pass the required arguments:
+
+```c#
+var service = composition.CreateService(userId);
+```
+
+### Resolve methods were not generated
+
+Check `Hint.Resolve`. When it is `Off`, `Resolve`/`ResolveByTag` methods are intentionally omitted and anonymous roots are not generated. Use named roots instead:
+
+```c#
+var service = composition.Service;
+```
+
+### Resolve cannot create a root with root arguments
+
+`Resolve`/`ResolveByTag` methods do not have a place to pass root arguments. Use the generated root method directly, or disable `Resolve` with `Hint.Resolve = Off` to avoid warnings and keep the generated API explicit.
+
+### A lock appears in generated code
+
+Pure.DI generates synchronization for thread-safe access to cached instances when needed. To remove it only when composition access is known to be single-threaded, use:
+
+```c#
+DI.Setup("Composition")
+    .Hint(Hint.ThreadSafe, "Off");
+```
+
+### Dispose or DisposeAsync was generated
+
+The composition tracks singleton and scoped instances that implement `IDisposable` or `IAsyncDisposable`. Dispose the composition when it owns such instances:
+
+```c#
+using var composition = new Composition();
+```
+
+or:
+
+```c#
+await using var composition = new Composition();
+```
+
+### Generated code is hard to read
+
+Temporarily enable `Hint.FormatCode` and save generated files with `EmitCompilerGeneratedFiles`. For graph-level inspection, enable `Hint.ToString` and use the Mermaid diagram.
+
+</details>
+
 <details>
 <summary>Performance profiling</summary>
 

src/Pure.DI.Core/Core/Code/ClassCommenter.cs

@@ -136,7 +136,19 @@ IReadOnlyCollection<string> CreateRootTerms(Root root)
                 IReadOnlyCollection<string> CreateRootDescriptions(Root root) =>
                     root.Source.Comments.Count > 0
                         ? root.Source.Comments.Select(comment => comments.Escape(comments.GetText(comment))).ToList()
-                        : [$"Provides a composition root of type {formatter.FormatRef(root.Node.Type)}."];
+                        : [CreateRootDescription(root)];
+
+                string CreateRootDescription(Root root)
+                {
+                    var description = new StringBuilder();
+                    description.Append($"Provides a composition root of type {formatter.FormatRef(root.Node.Type)}.");
+                    if (root.RootArgs.Length > 0)
+                    {
+                        description.Append($" This root uses root arguments and cannot be resolved by generated {hints.ResolveMethodName}/{hints.ResolveByTagMethodName} methods.");
+                    }
+
+                    return description.ToString();
+                }
             }
 
             var root = orderedRoots.Find(i => i.IsPublic);

src/Pure.DI.Core/Core/Code/ParameterizedConstructorCommenter.cs

@@ -13,7 +13,7 @@ public void AddComments(CompositionCode composition, Unit unit)
 
         var code = composition.Code;
         code.AppendLine("/// <summary>");
-        code.AppendLine($"/// This parameterized constructor creates a new instance of <see cref=\"{composition.Name.ClassName}\"/> with arguments.");
+        code.AppendLine($"/// This parameterized constructor creates a new instance of <see cref=\"{composition.Name.ClassName}\"/> with composition arguments used by the object graph.");
         code.AppendLine("/// </summary>");
         foreach (var arg in composition.ClassArgs.GetArgsOfKind(ArgKind.Composition))
         {
@@ -34,13 +34,13 @@ public void AddComments(CompositionCode composition, Unit unit)
             }
             else
             {
-                code.AppendLine($"/// <param name=\"{mdArg.ArgName}\">The composition argument of type {formatter.FormatRef(mdArg.Type)}.</param>");
+                code.AppendLine($"/// <param name=\"{mdArg.ArgName}\">The composition argument of type {formatter.FormatRef(mdArg.Type)}. Only arguments used by roots or their dependencies appear in this constructor.</param>");
             }
         }
 
         foreach (var arg in composition.SetupContextArgs.Where(i => i.Kind == SetupContextKind.Argument))
         {
-            code.AppendLine($"/// <param name=\"{arg.Name}\">The setup context of type {formatter.FormatRef(arg.Type)}.</param>");
+            code.AppendLine($"/// <param name=\"{arg.Name}\">The setup context argument of type {formatter.FormatRef(arg.Type)} copied from a dependent setup.</param>");
         }
     }
 }

src/Pure.DI.Core/Core/Code/Parts/ApiMembersBuilder.cs

@@ -9,8 +9,8 @@ sealed class ApiMembersBuilder(
     : IClassPartBuilder
 {
     private const string CommentSummaryStart = "/// <summary>";
-    private const string CommentSummary = "/// Resolves the composition root.";
-    private const string CommentSummaryByTag = "/// Resolves the composition root by tag.";
+    private const string CommentSummary = "/// Resolves a generated composition root that does not require root arguments.";
+    private const string CommentSummaryByTag = "/// Resolves a generated composition root by tag when the root does not require root arguments.";
     private const string CommentSummaryFinish = "/// </summary>";
     private const string CommentParamType = "/// <param name=\"type\">The type of the composition root.</param>";
     private const string CommentParamTag = "/// <param name=\"tag\">The tag of a composition root.</param>";
@@ -176,7 +176,7 @@ public CompositionCode Build(CompositionCode composition)
     private static void FinishComments(Lines apiCode)
     {
         apiCode.AppendLine("/// <returns>An instance of a composition root.</returns>");
-        apiCode.AppendLine($"/// <exception cref=\"{Names.CannotResolveExceptionTypeName}\">Will be thrown if the corresponding composition root was not specified. To specify a composition root use API method such as <see cref=\"{Names.IConfigurationTypeName}.Root{{T}}\"/>.</exception>");
+        apiCode.AppendLine($"/// <exception cref=\"{Names.CannotResolveExceptionTypeName}\">Will be thrown if the corresponding composition root was not specified or if the root requires root arguments. To specify a composition root use API method such as <see cref=\"{Names.IConfigurationTypeName}.Root{{T}}\"/>.</exception>");
         apiCode.AppendLine($"/// <seealso cref=\"{Names.IConfigurationTypeName}.RootBind{{T}}\"/>");
         apiCode.AppendLine($"/// <seealso cref=\"{Names.IConfigurationTypeName}.Roots{{T}}\"/>");
         apiCode.AppendLine($"/// <seealso cref=\"{Names.IConfigurationTypeName}.Builder{{T}}\"/>");

src/Pure.DI.Core/Core/Code/Parts/DisposeMethodBuilder.cs

@@ -27,7 +27,7 @@ public CompositionCode Build(CompositionCode composition)
         if (isCommentsEnabled)
         {
             code.AppendLine("/// <summary>");
-            code.AppendLine("/// <inheritdoc/>");
+            code.AppendLine("/// Disposes tracked singleton and scoped instances created by this composition.");
             code.AppendLine("/// </summary>");
         }
 
@@ -79,7 +79,7 @@ public CompositionCode Build(CompositionCode composition)
             if (isCommentsEnabled)
             {
                 code.AppendLine("/// <summary>");
-                code.AppendLine("/// <inheritdoc/>");
+                code.AppendLine("/// Asynchronously disposes tracked singleton and scoped instances created by this composition.");
                 code.AppendLine("/// </summary>");
             }
 

src/Pure.DI.Core/Core/Code/RootMethodsCommenter.cs

@@ -7,7 +7,8 @@ sealed class RootMethodsCommenter(
 {
     public void AddComments(CompositionCode composition, Root root)
     {
-        if (!composition.Hints.IsCommentsEnabled)
+        var hints = composition.Hints;
+        if (!hints.IsCommentsEnabled)
         {
             return;
         }
@@ -47,6 +48,13 @@ public void AddComments(CompositionCode composition, Root root)
                 code.AppendLine("/// </para>");
             }
 
+            if (root.RootArgs.Length > 0)
+            {
+                code.AppendLine("/// <para>");
+                code.AppendLine($"/// This root requires root arguments and is generated as a method. It cannot be resolved by generated {hints.ResolveMethodName}/{hints.ResolveByTagMethodName} methods.");
+                code.AppendLine("/// </para>");
+            }
+
             if (!root.IsPublic)
             {
                 return;