Generate auto-generated comments. Lots of docs

Author: datacute

.github/copilot-instructions.md

@@ -0,0 +1,30 @@
+# Internal Agent Instructions
+
+Purpose: Helper source files (embedded) for .NET incremental generators; keep output deterministic and public API stable.
+
+## 1. Scope
+Chat = terse (summary + reason + minimal diff). Repo docs = rich (rationale, examples, edge cases, perf). Additive edits only.
+
+## 2. Platform & Stability
+netstandard2.0 / C# 7.3. No newer BCL APIs. Preserve public type & member names.
+
+## 3. Guards
+Each helper file:
+```
+#if !DATACUTE_EXCLUDE_<UPPERCASENAME>
+// contents
+#endif
+```
+Nest or document dependencies.
+
+## 4. Editing & Diffs
+Show only changed lines (≤3 lines context). Fenced blocks for multi‑line examples. Short reason (perf / determinism / clarity / bug fix). No change‑log comments. UK English.
+
+## 5. Documentation
+XML doc first sentence = summary; follow with behaviour / perf / pitfalls if useful. READMEs may include: Overview, Why, Key APIs, Examples, Performance, Dependencies, Exclusion Flags, Instrumentation. Document public surface only (internal/private only if cross‑file contract). Chat brevity does not apply to repo docs.
+
+## 6. Chat Response Format
+1. Summary (1–2 lines)  2. Diff (changed lines) OR fenced example  3. Optional next steps (label “Optional”).
+
+## 7. Assumptions
+If unspecified, state one reversible assumption and proceed.

IncrementalGeneratorExtensions.Content/Datacute/IncrementalGeneratorExtensions/AttributeContextAndData.cs

@@ -1,9 +1,10 @@
-// <auto-generated>
-// This file is part of the Datacute.IncrementalGeneratorExtensions package.
-// It is included as a source file and should not be modified.
-// </auto-generated>
-
-#if !DATACUTE_EXCLUDE_ATTRIBUTECONTEXTANDDATA && !DATACUTE_EXCLUDE_TYPECONTEXT
+#if !DATACUTE_EXCLUDE_ATTRIBUTECONTEXTANDDATA // Feature: AttributeContextAndData
+#if DATACUTE_EXCLUDE_TYPECONTEXT
+#error AttributeContextAndData requires TypeContext (remove DATACUTE_EXCLUDE_TYPECONTEXT or also exclude DATACUTE_EXCLUDE_ATTRIBUTECONTEXTANDDATA)
+#endif
+#if DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAY
+#error AttributeContextAndData requires EquatableImmutableArray (remove DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAY or also exclude DATACUTE_EXCLUDE_ATTRIBUTECONTEXTANDDATA)
+#endif
 using System;
 using System.Collections.Immutable;
 using System.Text;
@@ -338,4 +339,4 @@ private static bool BootstrapGetIsNullableContextEnabled(SemanticModel semanticM
         }
     }
 }
-#endif
+#endif // !DATACUTE_EXCLUDE_ATTRIBUTECONTEXTANDDATA

IncrementalGeneratorExtensions.Content/Datacute/IncrementalGeneratorExtensions/AttributeContextAndDataExtensions.cs

@@ -1,14 +1,13 @@
-// <auto-generated>
-// This file is part of the Datacute.IncrementalGeneratorExtensions package.
-// It is included as a source file and should not be modified.
-// </auto-generated>
-
-#if !DATACUTE_EXCLUDE_ATTRIBUTECONTEXTANDDATAEXTENSIONS && !DATACUTE_EXCLUDE_ATTRIBUTECONTEXTANDDATA && !DATACUTE_EXCLUDE_TYPECONTEXT
+#if !DATACUTE_EXCLUDE_ATTRIBUTECONTEXTANDDATAEXTENSIONS // Feature: AttributeContextAndDataExtensions
+#if !DATACUTE_EXCLUDE_ATTRIBUTECONTEXTANDDATA // Dependency: AttributeContextAndData
 using System;
 using Microsoft.CodeAnalysis;
 
 namespace Datacute.IncrementalGeneratorExtensions
 {
+    /// <summary>
+    /// Extension methods for wiring up <see cref="AttributeContextAndData{T}"/> collection into an incremental generator pipeline.
+    /// </summary>
     public static class AttributeContextAndDataExtensions
     {
         /// <summary>
@@ -42,11 +41,12 @@ public static IncrementalValuesProvider<AttributeContextAndData<T>> SelectAttrib
                     predicate: AttributeContextAndData<T>.Predicate,
                     transform: (syntaxContext, token) =>
                         AttributeContextAndData<T>.Transform(syntaxContext, attributeDataCollector, token))
-#if !DATACUTE_EXCLUDE_LIGHTWEIGHTTRACEEXTENSIONS && !DATACUTE_EXCLUDE_LIGHTWEIGHT && !DATACUTE_EXCLUDE_GENERATORSTAGE
+#if !DATACUTE_EXCLUDE_LIGHTWEIGHTTRACEEXTENSIONS && !DATACUTE_EXCLUDE_LIGHTWEIGHTTRACE && !DATACUTE_EXCLUDE_GENERATORSTAGE
                 .WithTrackingName(GeneratorStage.ForAttributeWithMetadataName);
 #else
                 ;
 #endif
     }
 }
-#endif
+#endif // !DATACUTE_EXCLUDE_ATTRIBUTECONTEXTANDDATA
+#endif // !DATACUTE_EXCLUDE_ATTRIBUTECONTEXTANDDATAEXTENSIONS

IncrementalGeneratorExtensions.Content/Datacute/IncrementalGeneratorExtensions/EquatableImmutableArray.cs

@@ -1,12 +1,6 @@
-// <auto-generated>
-// This file is part of the Datacute.IncrementalGeneratorExtensions package.
-// It is included as a source file and should not be modified.
-// </auto-generated>
-
-#if !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAY
+#if !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAY
 using System;
 using System.Collections;
-using System.Collections.Concurrent;
 using System.Collections.Generic;
 using System.Collections.Immutable;
 using System.Threading;
@@ -20,32 +14,75 @@ namespace Datacute.IncrementalGeneratorExtensions
     public sealed class EquatableImmutableArray<T> : IEquatable<EquatableImmutableArray<T>>, IReadOnlyList<T>
         where T : IEquatable<T>
     {
+        /// <summary>
+        /// Gets a shared empty instance of <see cref="EquatableImmutableArray{T}"/>.
+        /// </summary>
         public static EquatableImmutableArray<T> Empty { get; } = new EquatableImmutableArray<T>(ImmutableArray<T>.Empty, 0);
 
         // Static factory method with singleton handling
-        public static EquatableImmutableArray<T> Create(ImmutableArray<T> values, CancellationToken cancellationToken = default) 
-            => EquatableImmutableArrayInstanceCache<T>.GetOrCreate(values, cancellationToken);
+        /// <summary>
+        /// Creates an <see cref="EquatableImmutableArray{T}"/> for the provided immutable array, reusing a cached instance when possible.
+        /// </summary>
+        /// <param name="values">The immutable array backing the equatable wrapper.</param>
+        /// <param name="cancellationToken">A cancellation token.</param>
+        /// <returns>An instance representing the supplied values (possibly a cached singleton for empty).</returns>
+        public static EquatableImmutableArray<T> Create(ImmutableArray<T> values, CancellationToken cancellationToken = default)
+        {
+            if (values.IsEmpty)
+                return Empty;
+#if DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAYINSTANCECACHE
+            // Cache disabled: compute hash directly and return a new instance (no reuse / instrumentation events)
+            var comparer = EqualityComparer<T>.Default;
+            int hash = CalculateHashCode(values, comparer, 0, 0);
+            return new EquatableImmutableArray<T>(values, hash);
+#else
+            return EquatableImmutableArrayInstanceCache<T>.GetOrCreate(values, cancellationToken);
+#endif
+        }
 
         private readonly ImmutableArray<T> _values;
         private readonly int _hashCode;
-        private readonly int _length;
 
+        /// <summary>
+        /// Gets the element at the specified index.
+        /// </summary>
+        /// <param name="index">Zero-based index.</param>
         public T this[int index] => _values[index];
-        public int Count => _length;
-        
+        /// <summary>
+        /// Gets the number of elements in the array.
+        /// </summary>
+        public int Count => _values.Length;
+
         // Properties Duplicated from ImmutableArray<T>
-        public int Length => _length;
-        public bool IsEmpty => _length == 0;
+
+        /// <summary>
+        /// Gets the number of elements in the array (alias of <see cref="Count"/>).
+        /// </summary>
+        public int Length => _values.Length;
+        /// <summary>
+        /// True if the underlying array has length 0.
+        /// </summary>
+        public bool IsEmpty => _values.Length == 0;
+        /// <summary>
+        /// True if the underlying immutable array is in its default (uninitialised) state.
+        /// </summary>
         public bool IsDefault => _values.IsDefault;
+        /// <summary>
+        /// True if the underlying immutable array is either default or empty.
+        /// </summary>
         public bool IsDefaultOrEmpty => _values.IsDefaultOrEmpty;
 
         internal EquatableImmutableArray(ImmutableArray<T> values, int hashCode)
         {
             _values = values;
-            _length = values.Length;
             _hashCode = hashCode;
         }
 
+        /// <summary>
+        /// Determines value equality with another <see cref="EquatableImmutableArray{T}"/>.
+        /// </summary>
+        /// <param name="other">The other instance.</param>
+        /// <returns>True if both contain the same sequence of values; otherwise false.</returns>
         public bool Equals(EquatableImmutableArray<T> other)
         {
             // Fast reference equality check
@@ -57,17 +94,18 @@ public bool Equals(EquatableImmutableArray<T> other)
             if (_hashCode != other._hashCode) return false;
 
             // We're really unlikely to get here, as we're using an instance cache
-            // so we've probably encountered a hash collision
-            
+            // so we've probably encountered a hash collision,
+            // or the instance cache is disabled.
+
             // Compare array lengths
-            if (_length != other._length) return false;
+            if (_values.Length != other._values.Length) return false;
 
             // If both are empty, they're equal
-            if (_length == 0) return true;
+            if (_values.Length == 0) return true;
 
             // Element-by-element comparison
             var comparer = EqualityComparer<T>.Default;
-            for (int i = 0; i < _length; i++)
+            for (int i = 0; i < _values.Length; i++)
             {
                 if (!comparer.Equals(_values[i], other._values[i]))
                     return false;
@@ -76,12 +114,30 @@ public bool Equals(EquatableImmutableArray<T> other)
             return true;
         }
 
+        /// <inheritdoc />
         public override bool Equals(object obj) => obj is EquatableImmutableArray<T> other && Equals(other);
 
+        /// <inheritdoc />
         public override int GetHashCode() => _hashCode;
 
         IEnumerator<T> IEnumerable<T>.GetEnumerator() => ((IEnumerable<T>)_values).GetEnumerator();
         IEnumerator IEnumerable.GetEnumerator() => ((IEnumerable)_values).GetEnumerator();
+
+        internal static int CalculateHashCode(ImmutableArray<T> values, EqualityComparer<T> comparer, int currentHash, int startIndex)
+        {
+            int hash = currentHash;
+            for (var index = startIndex; index < values.Length; index++)
+            {
+                var value = values[index];
+                hash = HashHelpers_Combine(hash, value == null ? 0 : comparer.GetHashCode(value));
+            }
+            return hash;
+        }
+        internal static int HashHelpers_Combine(int h1, int h2)
+        {
+            uint rol5 = ((uint)h1 << 5) | ((uint)h1 >> 27);
+            return ((int)rol5 + h1) ^ h2;
+        }
     }
 }
 #endif

IncrementalGeneratorExtensions.Content/Datacute/IncrementalGeneratorExtensions/EquatableImmutableArrayExtensions.cs

@@ -1,9 +1,5 @@
-// <auto-generated>
-// This file is part of the Datacute.IncrementalGeneratorExtensions package.
-// It is included as a source file and should not be modified.
-// </auto-generated>
-
-#if !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAYEXTENSIONS
+#if !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAYEXTENSIONS // Feature: EquatableImmutableArrayExtensions
+#if !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAY // Dependency: EquatableImmutableArray
 using System;
 using System.Collections.Generic;
 using System.Collections.Immutable;
@@ -150,11 +146,18 @@ public static EquatableImmutableArray<T> ToEquatableImmutableArray<TSource,T>(th
             where TRight : IEquatable<TRight>
             => provider1.Combine(provider2.CollectEquatable());
 
+        /// <summary>
+        /// Collects an <see cref="IncrementalValuesProvider{T}"/> and converts the <see cref="ImmutableArray{T}"/> to an <see cref="EquatableImmutableArray{T}"/>.
+        /// </summary>
+        /// <param name="provider">The incremental values provider to collect.</param>
+        /// <typeparam name="T">The type of the elements in the provider, which must implement <see cref="IEquatable{T}"/>.</typeparam>
+        /// <returns>An <see cref="IncrementalValueProvider{T}"/> producing the collected values as an <see cref="EquatableImmutableArray{T}"/>.</returns>
         public static IncrementalValueProvider<EquatableImmutableArray<T>> CollectEquatable<T>(
             this IncrementalValuesProvider<T> provider) 
             where T : IEquatable<T>
             => provider.Collect().Select(EquatableImmutableArray<T>.Create);
 
     }
 }
-#endif
+#endif // !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAY
+#endif // !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAYEXTENSIONS

IncrementalGeneratorExtensions.Content/Datacute/IncrementalGeneratorExtensions/EquatableImmutableArrayInstanceCache.cs

@@ -1,9 +1,5 @@
-// <auto-generated>
-// This file is part of the Datacute.IncrementalGeneratorExtensions package.
-// It is included as a source file and should not be modified.
-// </auto-generated>
-
-#if !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAY
+#if !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAYINSTANCECACHE // Feature: EquatableImmutableArrayInstanceCache (optional)
+#if !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAY // Dependency: EquatableImmutableArray
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
@@ -114,7 +110,7 @@ public static EquatableImmutableArray<T> GetOrCreate(ImmutableArray<T> values, C
                 }
 
                 // No match found, calculate hash and create new instance
-                var hash = CalculateHashCode(values, comparer, firstElementHash, 1);
+                var hash = EquatableImmutableArray<T>.CalculateHashCode(values, comparer, firstElementHash, 1);
 #if !DATACUTE_EXCLUDE_LIGHTWEIGHTTRACE && !DATACUTE_EXCLUDE_GENERATORSTAGE
                 // Record a histogram of the array sizes we are being asked to create
                 LightweightTrace.IncrementCount(GeneratorStage.EquatableImmutableArrayCacheMiss, values.Length);
@@ -125,25 +121,7 @@ public static EquatableImmutableArray<T> GetOrCreate(ImmutableArray<T> values, C
                 return newResult;
             }
         }
-        
-        private static int CalculateHashCode(ImmutableArray<T> values, EqualityComparer<T> comparer, int currentHash, int hashedValues)
-        {
-            int hash = currentHash;
-            for (var index = hashedValues; index < values.Length; index++)
-            {
-                var value = values[index];
-                hash = HashHelpers_Combine(hash, value == null ? 0 : comparer.GetHashCode(value));
-            }
-            return hash;
-        }
-        
-        private static int HashHelpers_Combine(int h1, int h2)
-        {
-            // RyuJIT optimizes this to use the ROL instruction
-            // Related GitHub pull request: https://github.com/dotnet/coreclr/pull/1830
-            uint rol5 = ((uint)h1 << 5) | ((uint)h1 >> 27);
-            return ((int)rol5 + h1) ^ h2;
-        }
     }
 }
-#endif
+#endif // !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAY
+#endif // !DATACUTE_EXCLUDE_EQUATABLEIMMUTABLEARRAYINSTANCECACHE

IncrementalGeneratorExtensions.Content/Datacute/IncrementalGeneratorExtensions/GeneratorStage.cs

@@ -1,9 +1,4 @@
-// <auto-generated>
-// This file is part of the Datacute.IncrementalGeneratorExtensions package.
-// It is included as a source file and should not be modified.
-// </auto-generated>
-
-#if !DATACUTE_EXCLUDE_GENERATORSTAGE
+#if !DATACUTE_EXCLUDE_GENERATORSTAGE
 namespace Datacute.IncrementalGeneratorExtensions
 {
     /// <summary>

IncrementalGeneratorExtensions.Content/Datacute/IncrementalGeneratorExtensions/GeneratorStageDescriptions.cs

@@ -1,9 +1,5 @@
-// <auto-generated>
-// This file is part of the Datacute.IncrementalGeneratorExtensions package.
-// It is included as a source file and should not be modified.
-// </auto-generated>
-
-#if !DATACUTE_EXCLUDE_GENERATORSTAGEDESCRIPTIONS && !DATACUTE_EXCLUDE_GENERATORSTAGE
+#if !DATACUTE_EXCLUDE_GENERATORSTAGEDESCRIPTIONS // Feature: GeneratorStageDescriptions
+#if !DATACUTE_EXCLUDE_GENERATORSTAGE // Dependency: GeneratorStage
 using System.Collections.Generic;
 
 namespace Datacute.IncrementalGeneratorExtensions
@@ -74,4 +70,5 @@ public static class GeneratorStageDescriptions
         };
     }
 }
-#endif
+#endif // !DATACUTE_EXCLUDE_GENERATORSTAGE
+#endif // !DATACUTE_EXCLUDE_GENERATORSTAGEDESCRIPTIONS

IncrementalGeneratorExtensions.Content/Datacute/IncrementalGeneratorExtensions/IndentingLineAppender.cs

@@ -1,9 +1,4 @@
-// <auto-generated>
-// This file is part of the Datacute.IncrementalGeneratorExtensions package.
-// It is included as a source file and should not be modified.
-// </auto-generated>
-
-#if !DATACUTE_EXCLUDE_INDENTINGLINEAPPENDER
+#if !DATACUTE_EXCLUDE_INDENTINGLINEAPPENDER
 using System;
 using System.Collections.Generic;
 using System.IO;

IncrementalGeneratorExtensions.Content/Datacute/IncrementalGeneratorExtensions/LightweightTrace.cs

@@ -1,9 +1,4 @@
-// <auto-generated>
-// This file is part of the Datacute.IncrementalGeneratorExtensions package.
-// It is included as a source file and should not be modified.
-// </auto-generated>
-
-#if !DATACUTE_EXCLUDE_LIGHTWEIGHTTRACE
+#if !DATACUTE_EXCLUDE_LIGHTWEIGHTTRACE
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
@@ -15,7 +10,9 @@
 namespace Datacute.IncrementalGeneratorExtensions
 {
     /// <summary>
-    /// A lightweight tracing utility that allows for efficient logging of events and counters.
+    /// Zero-allocation instrumentation core for incremental source generators.
+    /// <para>Features: ring-buffer timestamped event trace; composite-key counters (id + value + mapping flag) for histograms & categorical counts; automatic method-call frequency counting; method entry/exit tagging; single-int key encoding to minimize memory & dictionary churn; unified AppendDiagnosticsComment output (counters + trace) embeddable in generated code.</para>
+    /// <para>Goal: fast, in-process behavioral visibility without external profilers or large allocations.</para>
     /// </summary>
     public static class LightweightTrace
     {