Apply documentation suggestions from Andrew's code review

Co-authored-by: Andrew Lock <[email protected]>

Author: anna-git

Datadog.Trace.Minimal.slnf

@@ -3,12 +3,14 @@
     "path": "Datadog.Trace.sln",
     "projects": [
       "tracer\\src\\Datadog.Trace.ClrProfiler.Managed.Loader\\Datadog.Trace.ClrProfiler.Managed.Loader.csproj",
-      "tracer\\src\\Datadog.Tracer.Native\\Datadog.Tracer.Native.DLL.vcxproj",
-      "tracer\\src\\Datadog.Tracer.Native\\Datadog.Tracer.Native.vcxproj",
       "tracer\\src\\Datadog.Trace.MSBuild\\Datadog.Trace.MSBuild.csproj",
-      "tracer\\src\\Datadog.Trace.Tools.Analyzers\\Datadog.Trace.Tools.Analyzers.csproj",
+      "tracer\\src\\Datadog.Trace.SourceGenerators\\Datadog.Trace.SourceGenerators.csproj",
       "tracer\\src\\Datadog.Trace.Tools.Analyzers.CodeFixes\\Datadog.Trace.Tools.Analyzers.CodeFixes.csproj",
+      "tracer\\src\\Datadog.Trace.Tools.Analyzers\\Datadog.Trace.Tools.Analyzers.csproj",
+      "tracer\\src\\Datadog.Tracer.Native\\Datadog.Tracer.Native.DLL.vcxproj",
+      "tracer\\src\\Datadog.Tracer.Native\\Datadog.Tracer.Native.vcxproj",
       "tracer\\src\\Datadog.Trace\\Datadog.Trace.csproj",
-      "tracer\\src\\Datadog.Trace.SourceGenerators\\Datadog.Trace.SourceGenerators.csproj"]
+      "tracer\\test\\Datadog.Trace.SourceGenerators.Tests\\Datadog.Trace.SourceGenerators.Tests.csproj"
+    ]
   }
 }

docs/development/Configuration/AddingConfigurationKeys.md

@@ -22,8 +22,10 @@ This guide explains how to add new configuration keys to the .NET Tracer. Config
 
 Configuration keys in the .NET Tracer are defined in two source files:
 
-- **`tracer/src/Datadog.Trace/Configuration/supported-configurations.json`** - Defines the configuration keys, their environment variable names, and fallback chains
-- **`tracer/src/Datadog.Trace/Configuration/supported-configurations-docs.yaml`** - Contains XML documentation for each key
+- **`tracer/src/Datadog.Trace/Configuration/supported-configurations.json`** - Defines the configuration keys, their 
+  environment variable names, and optional fallbacks.
+- **`tracer/src/Datadog.Trace/Configuration/supported-configurations-docs.yaml`** - Contains XML documentation for 
+  each key. We're using yaml here as it makes it easier for some of the long documentation summaries and formatting.
 
 Two source generators read these files at build time:
 
@@ -38,7 +40,10 @@ Two source generators read these files at build time:
 
 ### 1. Add the Configuration Key Definition
 
-Add your new configuration key to `tracer/src/Datadog.Trace/Configuration/supported-configurations.json`.
+Add your new configuration key to `tracer/src/Datadog.Trace/Configuration/supported-configurations.json`, specifying 
+an arbitrary version string (e.g. `"A"`, as shown below). and specifying the product if required. Any product name 
+is allowed, but try to reuse the existing ones (see [Common products](#common-products)) if it makes sense, as they will create another partial class, ie 
+ConfigurationKeys.ProductName.cs. Without a product name, the keys will go in the main class, ConfigurationKeys.cs.
 
 **Example:**
 ```json
@@ -77,13 +82,13 @@ OTEL_EXPORTER_OTLP_LOGS_TIMEOUT: |
 - **Do NOT include `<summary>` tags** - the source generator automatically wraps your documentation in `<summary>` tags
 - You can include `<seealso>` and `<see>` tags directly in the content - the source generator will extract `<seealso>` tags and place them outside the `<summary>` section as needed
 
-### 3. (Optional) Add Fallback Keys (Aliases)
+### 3. (Optional) Add Aliases
 
-Configuration keys can have **fallback keys** (also called aliases) that are checked in order of appearance when the primary key is not found. Add them to the `fallbacks` section in `supported-configurations.json`:
+Configuration keys can have **aliases** that are checked in order of appearance when the primary key is not found. Add them to the `aliases` section in `supported-configurations.json`:
 
 ```json
 {
-  "fallbacks": {
+  "aliases": {
     "OTEL_EXPORTER_OTLP_LOGS_TIMEOUT": [
       "OTEL_EXPORTER_OTLP_TIMEOUT"
     ]
@@ -93,9 +98,11 @@ Configuration keys can have **fallback keys** (also called aliases) that are che
 
 **How it works:**
 1. The configuration system first looks for `OTEL_EXPORTER_OTLP_LOGS_TIMEOUT`
-2. If not found, it checks `OTEL_EXPORTER_OTLP_TIMEOUT` (the fallback)
+2. If not found, it automatically checks `OTEL_EXPORTER_OTLP_TIMEOUT` (the alias)
 3. If still not found, it uses the default value
 
+The `ConfigKeyAliasesSwitcherGenerator` source generator automatically generates the alias resolution logic from this section. No additional code is needed - just use the primary configuration key constant and the aliases are handled transparently.
+
 **Use cases:**
 - **Specific → General fallback:** A specific key (e.g., logs timeout) falls back to a general key (e.g., overall timeout)
 - **Backward compatibility:** Renamed keys can fall back to their old names to maintain compatibility
@@ -119,7 +126,7 @@ If you need to explicitly control the constant name (e.g., for backward compatib
 
 ### 5. Build to Generate Code
 
-Build the `Datadog.Trace` project to run the source generator:
+Build the `Datadog.Trace` project to run the source generator, either using Nuke or by building the project directly from the command line or your IDE:
 
 ```bash
 # From repository root
@@ -147,6 +154,18 @@ var timeout = source.GetInt32(ConfigurationKeys.OpenTelemetry.ExporterOtlpLogsTi
 
 **Note:** The generated constants are in the `Datadog.Trace.Configuration` namespace.
 
+#### Syntax Analyzers
+
+The codebase includes Roslyn analyzers that enforce the use of configuration keys from the `ConfigurationKeys` classes:
+
+- **`ConfigurationBuilderWithKeysAnalyzer`**  - Enforces that `ConfigurationBuilder.WithKeys()` method calls only accept string constants from `ConfigurationKeys` or `PlatformKeys` classes, not hardcoded strings or variables.
+
+**Diagnostic rules:**
+- **DD0007**: Triggers when hardcoded string literals are used instead of configuration key constants
+- **DD0008**: Triggers when variables or expressions are used instead of configuration key constants
+
+These analyzers help prevent typos and ensure consistency across the codebase by enforcing compile-time validation of configuration keys.
+
 ### 7. Add to Telemetry Normalization Rules
 
 Configuration keys are reported in telemetry with normalized names. Add your key to the normalization rules:
@@ -190,7 +209,8 @@ Use the `product` field to organize related keys into nested classes:
 
 Generates: `ConfigurationKeys.OpenTelemetry.ExporterOtlpEndpoint`
 
-**Common products:**
+#### Common products
+
 - `OpenTelemetry` - OpenTelemetry-related keys
 - `CIVisibility` - CI Visibility keys
 - `Telemetry` - Telemetry configuration
@@ -230,7 +250,7 @@ DD_TRACE_SAMPLE_RATE: |
 var rate = source.GetDouble(ConfigurationKeys.GlobalSamplingRate);
 ```
 
-### Example 2: Configuration Key with Fallback
+### Example 2: Configuration Key with Aliases
 
 **supported-configurations.json:**
 ```json
@@ -245,7 +265,7 @@ var rate = source.GetDouble(ConfigurationKeys.GlobalSamplingRate);
       "product": "OpenTelemetry"
     }
   },
-  "fallbacks": {
+  "aliases": {
     "OTEL_EXPORTER_OTLP_LOGS_TIMEOUT": [
       "OTEL_EXPORTER_OTLP_TIMEOUT"
     ]
@@ -257,22 +277,20 @@ var rate = source.GetDouble(ConfigurationKeys.GlobalSamplingRate);
 ```yaml
 OTEL_EXPORTER_OTLP_LOGS_TIMEOUT: |
   Configuration key for the timeout in milliseconds for OTLP logs export.
-  Falls back to <see cref="ConfigurationKeys.OpenTelemetry.ExporterOtlpTimeoutMs"/> if not set.
+  Falls back to <see cref="ConfigurationKeys.OpenTelemetry.ExporterOtlpTimeout"/> if not set.
   Default value is 10000ms.
   <seealso cref="Datadog.Trace.Configuration.TracerSettings.OtlpLogsTimeoutMs"/>
 
 OTEL_EXPORTER_OTLP_TIMEOUT: |
   Configuration key for the general OTLP export timeout in milliseconds.
-  Used as fallback for specific timeout configurations.
+  Used as alias for specific timeout configurations.
   Default value is 10000ms.
 ```
 
 **Usage:**
 ```csharp
-// Reads OTEL_EXPORTER_OTLP_LOGS_TIMEOUT, falls back to OTEL_EXPORTER_OTLP_TIMEOUT
-var timeout = source.GetInt32(
-    ConfigurationKeys.OpenTelemetry.ExporterOtlpLogsTimeout,
-    ConfigurationKeys.OpenTelemetry.ExporterOtlpTimeout);
+// Reads OTEL_EXPORTER_OTLP_LOGS_TIMEOUT, automatically falls back to OTEL_EXPORTER_OTLP_TIMEOUT
+var timeout = source.GetInt32(ConfigurationKeys.OpenTelemetry.ExporterOtlpLogsTimeout);
 ```
 
 ### Example 3: Feature Flag
@@ -336,17 +354,19 @@ dotnet build tracer/src/Datadog.Trace/Datadog.Trace.csproj
 3. XML tags are properly closed
 4. Rebuild after YAML changes
 
-### Fallback not working
+### Aliases not working
 
 **Check:**
-1. Fallback key is defined in `configurations` section
-2. Fallback array is in correct order (first fallback is tried first)
-3. Using the correct overload of `GetXxx()` method that accepts fallback keys
+1. Alias key is defined in `supportedConfigurations` section
+2. Alias array is in correct order (first alias is tried first)
+3. Both `ConfigurationKeysGenerator` and `ConfigKeyAliasesSwitcherGenerator` ran successfully during build
 
 ## Related Files
 
-- **Source generator:** `tracer/src/Datadog.Trace.SourceGenerators/Configuration/ConfigurationKeysGenerator.cs`
+- **Source generators:** 
+  - `tracer/src/Datadog.Trace.SourceGenerators/Configuration/ConfigurationKeysGenerator.cs` - Generates configuration key constants
+  - `tracer/src/Datadog.Trace.SourceGenerators/Configuration/ConfigKeyAliasesSwitcherGenerator.cs` - Generates alias resolution logic
 - **Configuration source:** `tracer/src/Datadog.Trace/Configuration/supported-configurations.json`
 - **Documentation source:** `tracer/src/Datadog.Trace/Configuration/supported-configurations-docs.yaml`
 - **Telemetry rules:** `tracer/test/Datadog.Trace.Tests/Telemetry/config_norm_rules.json`
-- **Generated output:** `tracer/src/Datadog.Trace/Generated/<tfm>/Datadog.Trace.SourceGenerators/ConfigurationKeysGenerator/`
+- **Generated output:** `tracer/src/Datadog.Trace/Generated/<tfm>/Datadog.Trace.SourceGenerators/`

tracer/src/Datadog.Trace.SourceGenerators/Configuration/ConfigKeyAliasesSwitcherGenerator.cs

@@ -13,10 +13,7 @@
 using Datadog.Trace.SourceGenerators;
 using Datadog.Trace.SourceGenerators.Helpers;
 using Microsoft.CodeAnalysis;
-using Microsoft.CodeAnalysis.CSharp;
-using Microsoft.CodeAnalysis.CSharp.Syntax;
 using Microsoft.CodeAnalysis.Text;
-using static Microsoft.CodeAnalysis.CSharp.SyntaxFactory;
 
 /// <summary>
 /// Source generator that reads supported-configurations.json and generates a switch case
@@ -69,8 +66,7 @@ private static void Execute(SourceProductionContext context, Result<Configuratio
 
         // Generate source code even if there are errors (use empty configuration as fallback)
         var configurationAliases = result.Value ?? new ConfigurationAliases(new Dictionary<string, string[]>());
-        var compilationUnit = GenerateConfigurationKeyMatcher(configurationAliases);
-        var generatedSource = compilationUnit.NormalizeWhitespace(eol: "\n").ToFullString();
+        var generatedSource = GenerateConfigurationKeyMatcher(configurationAliases);
         context.AddSource($"{ClassName}.g.cs", SourceText.From(generatedSource, Encoding.UTF8));
     }
 
@@ -197,97 +193,58 @@ private static DiagnosticInfo CreateDiagnosticInfo(string id, string title, stri
         return new DiagnosticInfo(descriptor, Location.None);
     }
 
-    private static CompilationUnitSyntax GenerateConfigurationKeyMatcher(ConfigurationAliases configurationAliases)
+    private static string GenerateConfigurationKeyMatcher(ConfigurationAliases configurationAliases)
     {
-        var getAliasesMethod = GenerateGetAliasesMethod(configurationAliases);
-
-        var classDeclaration = ClassDeclaration(ClassName)
-                              .WithModifiers(TokenList(Token(SyntaxKind.InternalKeyword), Token(SyntaxKind.StaticKeyword), Token(SyntaxKind.PartialKeyword)))
-                              .WithLeadingTrivia(
-                                   Comment(Constants.FileHeader),
-                                   Comment("/// <summary>"),
-                                   Comment("/// Generated configuration key matcher that handles main keys and aliases."),
-                                   Comment("/// This file is auto-generated from supported-configurations.json and supported-configurations-docs.yaml. Do not edit this file directly. The source generator will regenerate it on build."),
-                                   Comment("/// </summary>"))
-                              .WithMembers(
-                                   List<MemberDeclarationSyntax>(
-                                   [
-                                       getAliasesMethod
-                                   ]));
-
-        var namespaceDeclaration = FileScopedNamespaceDeclaration(
-                QualifiedName(
-                    QualifiedName(
-                        IdentifierName("Datadog"),
-                        IdentifierName("Trace")),
-                    IdentifierName("Configuration")))
-           .WithMembers(SingletonList<MemberDeclarationSyntax>(classDeclaration));
-
-        return CompilationUnit()
-              .WithUsings(
-                   SingletonList(
-                       UsingDirective(IdentifierName("System"))))
-              .WithMembers(SingletonList<MemberDeclarationSyntax>(namespaceDeclaration));
-    }
-
-    private static MethodDeclarationSyntax GenerateGetAliasesMethod(ConfigurationAliases configurationAliases)
-    {
-        var switchArms = new List<SwitchExpressionArmSyntax>();
-
-        // Add cases for keys that have aliases
-        foreach (var alias in configurationAliases.Aliases.OrderBy(a => a.Key))
+        var sb = new StringBuilder();
+
+        // File header
+        sb.Append(Constants.FileHeader);
+
+        // Namespace
+        sb.AppendLine("namespace Datadog.Trace.Configuration;");
+        sb.AppendLine();
+
+        // Class XML documentation
+        sb.AppendLine("/// <summary>");
+        sb.AppendLine("/// Generated configuration key matcher that handles main keys and aliases.");
+        sb.AppendLine("/// Do not edit this file directly as it is auto-generated from supported-configurations.json and supported-configurations-docs.yaml.");
+        sb.AppendLine("/// For more info, see docs/development/Configuration/AddingConfigurationKeys.md");
+        sb.AppendLine("/// </summary>");
+
+        // Class declaration
+        sb.AppendLine("internal static partial class ConfigKeyAliasesSwitcher");
+        sb.AppendLine("{");
+
+        // Method XML documentation
+        sb.AppendLine("    /// <summary>");
+        sb.AppendLine("    /// Gets all aliases for the given configuration key.");
+        sb.AppendLine("    /// </summary>");
+        sb.AppendLine("    /// <param name=\"mainKey\">The configuration key.</param>");
+        sb.AppendLine("    /// <returns>An array of aliases for the key, or empty array if no aliases exist.</returns>");
+
+        // Method signature
+        sb.AppendLine("    public static string[] GetAliases(string mainKey) => mainKey switch");
+        sb.AppendLine("    {");
+
+        // Generate switch cases for each alias
+        foreach (var kvp in configurationAliases.Aliases.OrderBy(a => a.Key))
         {
-            var mainKey = alias.Key;
-            var aliasKeys = alias.Value;
+            var mainKey = kvp.Key;
+            var aliases = kvp.Value;
 
-            // Create collection expression elements
-            var collectionElements = aliasKeys
-                                    .OrderBy(a => a)
-                                    .Select(aliasKey => ExpressionElement(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(aliasKey))))
-                                    .Cast<CollectionElementSyntax>()
-                                    .ToArray();
-
-            // Create collection expression [ "alias1", "alias2" ]
-            var collectionExpression = CollectionExpression(SeparatedList(collectionElements));
+            // Build the collection expression
+            var aliasesStr = string.Join(", ", aliases.Select(a => $"\"{a}\""));
+            sb.AppendLine($"        \"{mainKey}\" => [{aliasesStr}],");
+        }
 
-            // Create switch arm: "DD_AGENT_HOST" => [ "alias1", "alias2" ],
-            var switchArm = SwitchExpressionArm(
-                ConstantPattern(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(mainKey))),
-                collectionExpression);
+        // Default case
+        sb.AppendLine("        _ => []");
 
-            switchArms.Add(switchArm);
-        }
+        // Close method and class
+        sb.AppendLine("    };");
+        sb.AppendLine("}");
 
-        // Add default case: _ => []
-        var defaultArm = SwitchExpressionArm(
-            DiscardPattern(),
-            CollectionExpression());
-
-        switchArms.Add(defaultArm);
-
-        // Create switch expression: mainKey switch { ... }
-        var switchExpression = SwitchExpression(
-            IdentifierName(MainKeyParamName),
-            SeparatedList(switchArms));
-
-        return MethodDeclaration(
-                   ArrayType(PredefinedType(Token(SyntaxKind.StringKeyword)))
-                      .WithRankSpecifiers(SingletonList(ArrayRankSpecifier(SingletonSeparatedList<ExpressionSyntax>(OmittedArraySizeExpression())))),
-                   "GetAliases")
-              .WithModifiers(TokenList(Token(SyntaxKind.PublicKeyword), Token(SyntaxKind.StaticKeyword)))
-              .WithParameterList(
-                   ParameterList(
-                       SingletonSeparatedList(
-                           Parameter(Identifier(MainKeyParamName))
-                              .WithType(PredefinedType(Token(SyntaxKind.StringKeyword))))))
-              .WithLeadingTrivia(
-                   Comment("/// <summary>"),
-                   Comment("/// Gets all aliases for the given configuration key."),
-                   Comment("/// </summary>"),
-                   Comment($"/// <param name=\"{MainKeyParamName}\">The configuration key.</param>"),
-                   Comment("/// <returns>An array of aliases for the key, or empty array if no aliases exist.</returns>"))
-              .WithExpressionBody(ArrowExpressionClause(switchExpression))
-              .WithSemicolonToken(Token(SyntaxKind.SemicolonToken));
+        return sb.ToString();
     }
 
     private sealed class ConfigurationAliases(Dictionary<string, string[]> aliases) : IEquatable<ConfigurationAliases>

tracer/src/Datadog.Trace.SourceGenerators/Configuration/ConfigurationKeysGenerator.cs

@@ -288,27 +288,21 @@ private static Dictionary<string, ConfigEntry> ParseConfigurationEntries(JsonEle
         return configurations;
     }
 
-    private static void AppendFileHeader(StringBuilder sb)
-    {
-        sb.Append(Constants.FileHeader);
-        sb.Append(Constants.ConfigurationGeneratorComment);
-    }
-
     private static string GenerateProductPartialClass(string product, List<KeyValuePair<string, ConfigEntry>> entries, Dictionary<string, ConstantNameMapping>? nameMapping)
     {
         var sb = new StringBuilder();
-
-        AppendFileHeader(sb);
+        sb.Append(Constants.FileHeader);
         sb.Append("namespace ").Append(Namespace).AppendLine(";");
         sb.AppendLine();
+        sb.AppendLine("/// <summary>");
+        sb.AppendLine("/// String constants for standard Datadog configuration keys.");
+        sb.AppendLine("/// Do not edit this file directly as it's auto-generated from supported-configurations.json and supported-configurations-docs.yaml");
+        sb.AppendLine("/// For more info, see docs/development/Configuration/AddingConfigurationKeys.md");
+        sb.AppendLine("/// </summary>");
 
         if (string.IsNullOrEmpty(product))
         {
             // Generate main class without nested product class
-            sb.AppendLine("/// <summary>");
-            sb.AppendLine("/// String constants for standard Datadog configuration keys.");
-            sb.AppendLine("/// Auto-generated from supported-configurations.json and supported-configurations-docs.yaml");
-            sb.AppendLine("/// </summary>");
             sb.AppendLine($"internal static partial class {GeneratedClassName}");
             sb.AppendLine("{");