feat(ToString): add configurable collection formatting to ToString generator

- Introduce `CollectionFormat` enum for `ToString` generation, enabling customizable rendering of collection properties (`Count`, `Elements`, `TypeAndCount`).
- Add unit tests for all modes and null handling.
- Update attribute, generator logic, and `README`.

Author: BoBoBaSs84

README.md

@@ -663,7 +663,7 @@ UserProfile second = builder.WithId(2).Build();
 
 ### 6. ToString Generator
 
-Generates a `ToString()` override for classes, returning a formatted string containing the class name and all (or selected) public readable property values in the format `ClassName { Prop1 = val1, Prop2 = val2 }`.
+Generates a `ToString()` override for classes, returning a formatted string containing the class name and all (or selected) public readable property values in the format `ClassName { Prop1 = val1, Prop2 = val2 }`. Collection properties (lists, arrays, dictionaries) are rendered with configurable formatting instead of the default type name.
 
 #### Attribute
 
@@ -674,6 +674,17 @@ Generates a `ToString()` override for classes, returning a formatted string cont
 **Parameters:**
 
 - `excludeProperties` - Optional list of property names to exclude from the generated `ToString()` output
+- `CollectionFormat` - Controls how collection properties are rendered (named argument, default: `CollectionFormat.Count`)
+
+**Collection Format Modes:**
+
+| Mode                                 | Description                                                             | Example output                 |
+| ------------------------------------ | ----------------------------------------------------------------------- | ------------------------------ |
+| `CollectionFormat.Count` _(default)_ | Shows element count only                                                | `Count = 3`                    |
+| `CollectionFormat.Elements`          | Inline elements for lists/arrays; `{key: value}` pairs for dictionaries | `[Alice, Bob]` / `{Alice: 10}` |
+| `CollectionFormat.TypeAndCount`      | Shows runtime type name and element count                               | `List\`1 (Count = 3)`          |
+
+`null` collections are always rendered as `null` regardless of the format mode.
 
 #### Example
 
@@ -698,6 +709,23 @@ public partial class User
     public string PasswordHash { get; set; }
     public string InternalNotes { get; set; }
 }
+
+// Collection properties — explicit Elements mode for full display
+[GenerateToString(CollectionFormat = CollectionFormat.Elements)]
+public partial class Team
+{
+    public string Name { get; set; }
+    public List<string> Members { get; set; }
+    public Dictionary<string, int> Scores { get; set; }
+}
+
+// Collection properties — Count mode
+[GenerateToString(CollectionFormat = CollectionFormat.Count)]
+public partial class TeamSummary
+{
+    public string Name { get; set; }
+    public List<string> Members { get; set; }
+}
 ```
 
 #### Generated Code
@@ -708,6 +736,11 @@ The generator creates a `ToString()` override on the partial class that:
 - Excludes properties specified in the attribute parameter
 - Formats output as `ClassName { Prop1 = val1, Prop2 = val2 }`
 - Returns `ClassName { }` when all properties are excluded
+- For collection properties, emits inline formatting based on `CollectionFormat`:
+  - `Count`: `Count = N`
+  - `Elements`: `[item1, item2]` for arrays/lists, `{key1: val1, key2: val2}` for dictionaries
+  - `TypeAndCount`: `TypeName (Count = N)`
+- For dictionary properties in `Elements` mode, emits a private generic helper `DictionaryToString<TKey, TValue>`
 
 #### Usage Example
 
@@ -733,6 +766,25 @@ var user = new User
 
 Console.WriteLine(user.ToString());
 // Output: User { Id = 42, Name = John Doe }
+
+var team = new Team
+{
+    Name = "Alpha",
+    Members = new List<string> { "Alice", "Bob", "Charlie" },
+    Scores = new Dictionary<string, int> { ["Alice"] = 10, ["Bob"] = 20 }
+};
+
+Console.WriteLine(team.ToString());
+// Output: Team { Name = Alpha, Members = [Alice, Bob, Charlie], Scores = {Alice: 10, Bob: 20} }
+
+var summary = new TeamSummary
+{
+    Name = "Beta",
+    Members = new List<string> { "Alice", "Bob", "Charlie" }
+};
+
+Console.WriteLine(summary.ToString());
+// Output: TeamSummary { Name = Beta, Members = Count = 3 }
 ```
 
 ### 7. Validator Generator

src/BB84.SourceGenerators/Attributes/GenerateToStringAttribute.cs

@@ -5,6 +5,28 @@
 // LICENSE file in the root directory of this source tree.
 namespace BB84.SourceGenerators.Attributes;
 
+/// <summary>
+/// Specifies how collection properties are formatted in the generated <c>ToString()</c> output.
+/// </summary>
+internal enum CollectionFormat
+{
+	/// <summary>
+	/// Shows only the element count: <c>Count = 3</c>.
+	/// </summary>
+	Count = 0,
+
+	/// <summary>
+	/// Formats elements inline: <c>[item1, item2]</c> for list-like collections and
+	/// <c>{key1: val1, key2: val2}</c> for dictionaries. This is the default.
+	/// </summary>
+	Elements = 1,
+
+	/// <summary>
+	/// Shows the runtime type name and element count: e.g. <c>List`1 (Count = 3)</c>.
+	/// </summary>
+	TypeAndCount = 2,
+}
+
 /// <summary>
 /// Indicates that the decorated <c>class</c> should have a <c>ToString()</c> override generated for it.
 /// The generated method returns a formatted string containing the class name and all (or selected)
@@ -24,4 +46,10 @@ public GenerateToStringAttribute() : this([])
 	/// Gets the property names to exclude from the generated <c>ToString()</c> output.
 	/// </summary>
 	public string[] ExcludeProperties => excludeProperties;
+
+	/// <summary>
+	/// Gets or sets how collection properties are formatted in the generated <c>ToString()</c> output.
+	/// Defaults to <see cref="CollectionFormat.Count"/>.
+	/// </summary>
+	public CollectionFormat CollectionFormat { get; set; } = CollectionFormat.Count;
 }

src/BB84.SourceGenerators/Helpers/GeneratorHelpers.cs

@@ -254,12 +254,16 @@ internal static bool TryCreateContext(
 	/// When not <see langword="null"/>, checks whether the property type is decorated with the specified attribute
 	/// and sets <see cref="PropertyDescriptor.IsCloneable"/> accordingly.
 	/// </param>
+	/// <param name="detectCollections">
+	/// When <see langword="true"/>, detects collection types and sets <see cref="PropertyDescriptor.CollectionKind"/> accordingly.
+	/// </param>
 	/// <returns>An immutable array of <see cref="PropertyDescriptor"/> instances.</returns>
 	internal static ImmutableArray<PropertyDescriptor> GetPropertyDescriptors(
 		INamedTypeSymbol classSymbol,
 		HashSet<string>? excludedProperties = null,
 		bool requireSetter = false,
-		string? cloneableAttributeName = null)
+		string? cloneableAttributeName = null,
+		bool detectCollections = false)
 	{
 		ImmutableArray<PropertyDescriptor>.Builder builder = ImmutableArray.CreateBuilder<PropertyDescriptor>();
 
@@ -293,8 +297,11 @@ internal static ImmutableArray<PropertyDescriptor> GetPropertyDescriptors(
 						break;
 					}
 				}
+			}
 
-				// Detect collection types
+			// Detect collection types when explicitly requested or when cloneability checks are active
+			if (cloneableAttributeName is not null || detectCollections)
+			{
 				(collectionKind, elementTypeName, isElementCloneable, dictionaryValueTypeName, isDictionaryValueCloneable) =
 					DetectCollectionKind(propertySymbol.Type, cloneableAttributeName);
 			}
@@ -309,7 +316,8 @@ internal static ImmutableArray<PropertyDescriptor> GetPropertyDescriptors(
 	/// Detects the collection kind of a type symbol and extracts element type information.
 	/// </summary>
 	private static (CollectionKind Kind, string? ElementTypeName, bool IsElementCloneable, string? DictionaryValueTypeName, bool IsDictionaryValueCloneable) DetectCollectionKind(
-		ITypeSymbol typeSymbol, string cloneableAttributeName)
+		ITypeSymbol typeSymbol,
+		string? cloneableAttributeName)
 	{
 		// Unwrap nullable
 		if (typeSymbol is INamedTypeSymbol { OriginalDefinition.SpecialType: SpecialType.System_Nullable_T } nullable)
@@ -319,7 +327,7 @@ private static (CollectionKind Kind, string? ElementTypeName, bool IsElementClon
 		if (typeSymbol is IArrayTypeSymbol arrayType)
 		{
 			string elementType = arrayType.ElementType.ToFullyQualifiedDisplayString();
-			bool elementCloneable = HasAttribute(arrayType.ElementType, cloneableAttributeName);
+			bool elementCloneable = cloneableAttributeName is not null && HasAttribute(arrayType.ElementType, cloneableAttributeName);
 			return (CollectionKind.Array, elementType, elementCloneable, null, false);
 		}
 
@@ -332,23 +340,23 @@ private static (CollectionKind Kind, string? ElementTypeName, bool IsElementClon
 			{
 				string keyType = namedType.TypeArguments[0].ToFullyQualifiedDisplayString();
 				string valueType = namedType.TypeArguments[1].ToFullyQualifiedDisplayString();
-				bool valueCloneable = HasAttribute(namedType.TypeArguments[1], cloneableAttributeName);
+				bool valueCloneable = cloneableAttributeName is not null && HasAttribute(namedType.TypeArguments[1], cloneableAttributeName);
 				return (CollectionKind.Dictionary, keyType, false, valueType, valueCloneable);
 			}
 
 			// List<T>
 			if (originalDef == "System.Collections.Generic.List<T>")
 			{
 				string elementType = namedType.TypeArguments[0].ToFullyQualifiedDisplayString();
-				bool elementCloneable = HasAttribute(namedType.TypeArguments[0], cloneableAttributeName);
+				bool elementCloneable = cloneableAttributeName is not null && HasAttribute(namedType.TypeArguments[0], cloneableAttributeName);
 				return (CollectionKind.List, elementType, elementCloneable, null, false);
 			}
 
 			// ImmutableArray<T>
 			if (originalDef == "System.Collections.Immutable.ImmutableArray<T>")
 			{
 				string elementType = namedType.TypeArguments[0].ToFullyQualifiedDisplayString();
-				bool elementCloneable = HasAttribute(namedType.TypeArguments[0], cloneableAttributeName);
+				bool elementCloneable = cloneableAttributeName is not null && HasAttribute(namedType.TypeArguments[0], cloneableAttributeName);
 				return (CollectionKind.ImmutableArray, elementType, elementCloneable, null, false);
 			}
 
@@ -358,7 +366,7 @@ private static (CollectionKind Kind, string? ElementTypeName, bool IsElementClon
 				or "System.Collections.Generic.IReadOnlyCollection<T>")
 			{
 				string elementType = namedType.TypeArguments[0].ToFullyQualifiedDisplayString();
-				bool elementCloneable = HasAttribute(namedType.TypeArguments[0], cloneableAttributeName);
+				bool elementCloneable = cloneableAttributeName is not null && HasAttribute(namedType.TypeArguments[0], cloneableAttributeName);
 				return (CollectionKind.ReadOnlyCollection, elementType, elementCloneable, null, false);
 			}
 		}

src/BB84.SourceGenerators/ToStringGenerator.cs

@@ -22,29 +22,33 @@ namespace BB84.SourceGenerators;
 [Generator(LanguageNames.CSharp)]
 public sealed class ToStringGenerator : IIncrementalGenerator
 {
-	private static readonly string GeneratorAttributeName = typeof(GenerateToStringAttribute).FullName;
+	private static readonly (string MetadataName, string FullName, string ShortName) AttributeNames =
+		GeneratorHelpers.GetAttributeNames<GenerateToStringAttribute>();
 
 	/// <inheritdoc/>
 	public void Initialize(IncrementalGeneratorInitializationContext context)
-		=> GeneratorHelpers.RegisterClassGenerator(context, GeneratorAttributeName, Execute);
+		=> GeneratorHelpers.RegisterClassGenerator(context, AttributeNames.MetadataName, Execute);
 
 	private void Execute(SourceProductionContext context, (ClassDeclarationSyntax ClassSyntax, SemanticModel SemanticModel)? input)
 	{
 		if (!GeneratorHelpers.TryCreateContext(input, out GeneratorContext ctx))
 			return;
 
+		CollectionFormat collectionFormat = GetCollectionFormat(ctx.ClassDeclaration, ctx.SemanticModel);
 		HashSet<string> excludedProperties = GeneratorHelpers.GetExcludedProperties(ctx.ClassDeclaration, ctx.SemanticModel, nameof(GenerateToStringAttribute));
-		ImmutableArray<PropertyDescriptor> properties = GeneratorHelpers.GetPropertyDescriptors(ctx.ClassSymbol, excludedProperties);
+		ImmutableArray<PropertyDescriptor> properties = GeneratorHelpers.GetPropertyDescriptors(ctx.ClassSymbol, excludedProperties, detectCollections: true);
 
 		SourceBuilder sb = new();
 
 		sb.AppendAutoGeneratedWarning(GeneratorNames.ToStringGeneratorFullName);
 		sb.AppendNullableEnable();
+		sb.AppendUsing(NamespaceNames.System);
+		sb.AppendUsing(NamespaceNames.SystemCollectionsGeneric);
 		sb.AppendLine();
 		sb.OpenNamespace(ctx.NamespaceName);
 		sb.OpenOuterClasses(ctx.OuterClasses);
 
-		AppendPartialClass(sb, ctx.ClassName, ctx.Accessibility, properties);
+		AppendPartialClass(sb, ctx.ClassName, ctx.Accessibility, properties, collectionFormat);
 
 		sb.CloseOuterClasses(ctx.OuterClasses);
 		sb.CloseNamespace();
@@ -56,19 +60,41 @@ private void Execute(SourceProductionContext context, (ClassDeclarationSyntax Cl
 		context.AddSource(hintName, sb.ToString());
 	}
 
-	private static void AppendPartialClass(SourceBuilder sb, string className, string accessibility, ImmutableArray<PropertyDescriptor> properties)
+	private static void AppendPartialClass(SourceBuilder sb, string className, string accessibility, ImmutableArray<PropertyDescriptor> properties, CollectionFormat collectionFormat)
 	{
+		bool hasDictionary = collectionFormat == CollectionFormat.Elements
+			&& properties.Any(static p => p.CollectionKind == CollectionKind.Dictionary);
+
 		sb.OpenClass(accessibility, className);
 		sb.AppendLine("/// <inheritdoc/>");
 		sb.AppendLine("public override string ToString()");
 		sb.OpenBrace();
 
 		if (properties.Length == 0)
+		{
 			sb.AppendLine($"return \"{className} {{ }}\";");
+		}
 		else
+		{
+			foreach (PropertyDescriptor prop in properties)
+			{
+				if (prop.CollectionKind == CollectionKind.None)
+					continue;
+
+				sb.AppendLine($"string {prop.Name.ToLowerInvariant()} = {BuildCollectionFormatExpression(prop, collectionFormat)};");
+			}
+
 			sb.AppendLine($"return $\"{className} {{{{ {BuildFormatString(properties)} }}}}\";");
+		}
 
 		sb.CloseBrace();
+
+		if (hasDictionary)
+		{
+			sb.AppendLine();
+			AppendDictionaryFormatHelper(sb);
+		}
+
 		sb.CloseClass();
 	}
 
@@ -81,9 +107,102 @@ private static string BuildFormatString(ImmutableArray<PropertyDescriptor> prope
 			if (i > 0)
 				format.Append(", ");
 
-			format.Append($"{properties[i].Name} = {{{properties[i].Name}}}");
+			string token = properties[i].CollectionKind != CollectionKind.None
+				? $"{properties[i].Name.ToLowerInvariant()}"
+				: properties[i].Name;
+
+			format.Append($"{{nameof({properties[i].Name})}} = {{{token}}}");
 		}
 
 		return format.ToString();
 	}
+
+	private static string BuildCollectionFormatExpression(PropertyDescriptor prop, CollectionFormat format)
+	{
+		bool isImmutableArray = prop.CollectionKind == CollectionKind.ImmutableArray;
+		bool isArray = prop.CollectionKind == CollectionKind.Array;
+		bool isDictionary = prop.CollectionKind == CollectionKind.Dictionary;
+
+		// ImmutableArray<T> (non-nullable struct): IsValueType = true
+		// ImmutableArray<T>? (Nullable<ImmutableArray<T>>): IsValueType = false
+		bool isNullableImmutableArray = isImmutableArray && !prop.IsValueType;
+		bool isNonNullableImmutableArray = isImmutableArray && prop.IsValueType;
+
+		// Arrays and ImmutableArrays use .Length; all other collection types use .Count
+		bool usesLength = isArray || isImmutableArray;
+
+		// Expression for the non-null collection value
+		string directAccess = isNullableImmutableArray ? $"{prop.Name}.Value" : prop.Name;
+		string countAccess = usesLength ? $"{directAccess}.Length" : $"{directAccess}.Count";
+
+		// Null guard (null means no null check required for non-nullable value types)
+		string? nullGuard = isNonNullableImmutableArray
+			? null
+			: isNullableImmutableArray
+				? $"!{prop.Name}.HasValue"
+				: $"{prop.Name} == null";
+
+		string WrapGuard(string valueExpr)
+			=> nullGuard is not null ? $"{nullGuard} ? \"null\" : {valueExpr}" : valueExpr;
+
+		return format switch
+		{
+			CollectionFormat.Elements when isDictionary => $"DictionaryToString({prop.Name})",// The DictionaryToString helper handles null internally
+			CollectionFormat.Elements => WrapGuard($"\"[\" + string.Join(\", \", {directAccess}) + \"]\""),
+			CollectionFormat.Count => WrapGuard($"\"Count = \" + {countAccess}"),
+			CollectionFormat.TypeAndCount => WrapGuard($"{directAccess}.GetType().Name + \" (Count = \" + {countAccess} + \")\""),
+			_ => prop.Name,
+		};
+	}
+
+	private static void AppendDictionaryFormatHelper(SourceBuilder sb)
+	{
+		sb.AppendLine("private static string DictionaryToString<TKey, TValue>(IDictionary<TKey, TValue>? dictionary)");
+		sb.OpenBrace();
+		sb.AppendLine("if (dictionary == null)");
+		sb.Indent();
+		sb.AppendLine("return \"null\";");
+		sb.Outdent();
+		sb.AppendLine("List<string> parts = new List<string>(dictionary.Count);");
+		sb.AppendLine("foreach (KeyValuePair<TKey, TValue> kvp in dictionary)");
+		sb.Indent();
+		sb.AppendLine("parts.Add(kvp.Key + \": \" + kvp.Value);");
+		sb.Outdent();
+		sb.AppendLine("return \"{\" + string.Join(\", \", parts) + \"}\";");
+		sb.CloseBrace();
+	}
+
+	private static CollectionFormat GetCollectionFormat(ClassDeclarationSyntax classDeclaration, SemanticModel semanticModel)
+	{
+		foreach (AttributeListSyntax attributeList in classDeclaration.AttributeLists)
+		{
+			foreach (AttributeSyntax attribute in attributeList.Attributes)
+			{
+				string name = attribute.Name.ToString();
+
+				if (name != AttributeNames.ShortName && name != AttributeNames.FullName)
+					continue;
+
+				if (attribute.ArgumentList is null)
+					return CollectionFormat.Count;
+
+				foreach (AttributeArgumentSyntax arg in attribute.ArgumentList.Arguments)
+				{
+					if (arg.NameEquals?.Name.Identifier.Text != nameof(GenerateToStringAttribute.CollectionFormat))
+						continue;
+
+					Optional<object?> value = semanticModel.GetConstantValue(arg.Expression);
+
+					if (value.HasValue && value.Value is int intValue)
+						return (CollectionFormat)intValue;
+
+					break;
+				}
+
+				return CollectionFormat.Count;
+			}
+		}
+
+		return CollectionFormat.Count;
+	}
 }