Allow constants to define custom root comment summary

src/ThisAssembly.Constants/CSharp.sbntxt

@@ -74,7 +74,7 @@ namespace {{ Namespace }};
 {{ Visibility }}partial class ThisAssembly
 {
     /// <summary>
-    /// Provides access project-defined constants.
+    /// {{ RootArea.Comment }}
     /// </summary>
     {{ render RootArea }}
 }

src/ThisAssembly.Constants/ConstantsGenerator.cs

@@ -25,10 +25,15 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
                 && itemType == "Constant")
             .Select((x, ct) =>
             {
-                x.Right.GetOptions(x.Left).TryGetValue("build_metadata.Constant.Value", out var value);
-                x.Right.GetOptions(x.Left).TryGetValue("build_metadata.Constant.Type", out var type);
-                x.Right.GetOptions(x.Left).TryGetValue("build_metadata.Constant.Comment", out var comment);
-                x.Right.GetOptions(x.Left).TryGetValue("build_metadata.Constant.Root", out var root);
+                var options = x.Right.GetOptions(x.Left);
+                options.TryGetValue("build_metadata.Constant.Value", out var value);
+                options.TryGetValue("build_metadata.Constant.Type", out var type);
+                options.TryGetValue("build_metadata.Constant.Comment", out var comment);
+                options.TryGetValue("build_metadata.Constant.Root", out var root);
+                options.TryGetValue("build_metadata.Constant.RootComment", out var rootComment);
+
+                if (string.IsNullOrEmpty(rootComment))
+                    rootComment = "Provides access project-defined constants.";
 
                 // Revert auto-escaping due to https://github.com/dotnet/roslyn/issues/51692
                 if (value != null && value.StartsWith("|") && value.EndsWith("|"))
@@ -53,7 +58,7 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
                     }
                 }
 
-                return (name, value: value ?? "", type: string.IsNullOrWhiteSpace(type) ? null : type, comment: string.IsNullOrWhiteSpace(comment) ? null : comment, root!);
+                return (name, value: value ?? "", type: string.IsNullOrWhiteSpace(type) ? null : type, comment: string.IsNullOrWhiteSpace(comment) ? null : comment, root!, rootComment!);
             });
 
         // Read the ThisAssemblyNamespace property or default to null
@@ -72,9 +77,9 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
     }
 
     void GenerateConstant(SourceProductionContext spc,
-        (((string name, string value, string? type, string? comment, string root), ((string? ns, string? visibility), ParseOptions parse)), StatusOptions options) args)
+        (((string name, string value, string? type, string? comment, string root, string rootComment), ((string? ns, string? visibility), ParseOptions parse)), StatusOptions options) args)
     {
-        var (((name, value, type, comment, root), ((ns, visibility), parse)), options) = args;
+        var (((name, value, type, comment, root, rootComment), ((ns, visibility), parse)), options) = args;
         var cs = (CSharpParseOptions)parse;
 
         if (!string.IsNullOrWhiteSpace(ns) &&
@@ -93,7 +98,7 @@ void GenerateConstant(SourceProductionContext spc,
             comment = "/// " + string.Join(Environment.NewLine + "/// ", value.Replace("\\n", Environment.NewLine).Trim(['\r', '\n']).Split([Environment.NewLine], StringSplitOptions.None));
 
         // Revert normalization of newlines performed in MSBuild to workaround the limitation in editorconfig.
-        var rootArea = Area.Load([new(name, value.Replace("\\n", Environment.NewLine).Trim(['\r', '\n']), comment, type ?? "string"),], root);
+        var rootArea = Area.Load([new(name, value.Replace("\\n", Environment.NewLine).Trim(['\r', '\n']), comment, type ?? "string"),], root, rootComment);
         // For now, we only support C# though
         var file = parse.Language.Replace("#", "Sharp") + ".sbntxt";
         var template = Template.Parse(EmbeddedResource.GetContent(file), file);

src/ThisAssembly.Constants/Model.cs

@@ -22,7 +22,7 @@ record Model(Area RootArea, string? Namespace, bool IsPublic)
 }
 
 [DebuggerDisplay("Name = {Name}, NestedAreas = {NestedAreas.Count}, Values = {Values.Count}")]
-record Area(string Name, string Prefix)
+record Area(string Name, string Prefix, string Comment)
 {
     public List<Area> NestedAreas { get; init; } = new();
     public List<Constant> Values { get; init; } = new();
@@ -48,9 +48,9 @@ static string EscapeIdentifier(string identifier)
         return result;
     }
 
-    public static Area Load(List<Constant> constants, string rootArea = "Constants")
+    public static Area Load(List<Constant> constants, string rootArea = "Constants", string comment = "Provides access project-defined constants.")
     {
-        var root = new Area(rootArea, "");
+        var root = new Area(rootArea, "", comment);
 
         foreach (var constant in constants)
         {
@@ -96,7 +96,7 @@ static Area GetArea(Area area, IEnumerable<string> areaPath)
                         "Area name '{0}' is already in use as a value name under area '{1}'.",
                         areaName, currentArea.Name));
 
-                existing = new Area(areaName, currentArea.Prefix + areaName + ".");
+                existing = new Area(areaName, currentArea.Prefix + areaName + ".", "");
                 currentArea.NestedAreas.Add(existing);
             }
 

src/ThisAssembly.Constants/ThisAssembly.Constants.targets

@@ -10,6 +10,7 @@
     <CompilerVisibleItemMetadata Include="Constant" MetadataName="Value" />
     <CompilerVisibleItemMetadata Include="Constant" MetadataName="Type" />
     <CompilerVisibleItemMetadata Include="Constant" MetadataName="Root" />
+    <CompilerVisibleItemMetadata Include="Constant" MetadataName="RootComment" />
 
     <!-- Make sure we're always private to the referencing project. 
          Prevents analyzers from "flowing out" of the referencing project. -->