Inconsistency in StringBuilder.Equals(StringBuilder) documentation regarding Capacity comparison

[mahfeshar]

Type of issue

Outdated article

Description

There is a documentation mismatch in the StringBuilder.Equals(StringBuilder) method page. The "Returns" section and the "Example" output contradict the "Remarks" section for modern .NET versions (.NET Core 3.0+ and .NET 5+).

The Inconsistency:

1. Returns Section: It states that the method returns true if the instance and sb have equal string, Capacity, and MaxCapacity. This is only true for .NET Framework.
2. Example Output: The example shows that when Capacity is changed (in step b4), the result is False.

// Current doc says:
b4) sb1 equals sb2: False

3. Actual Behavior: In modern .NET (Core 3.0+), the source code confirms that Capacity is ignored. Running the same example on .NET 6/7/8/9 results in True for step b4.

Source Code Reference:
As seen in the implementation, the method only iterates through chunks to compare characters and checks the Length property, but never accesses the Capacity property.

Expected Documentation Update:

• The Returns section should be updated to clarify that Capacity is not considered in modern .NET.
• The Example Output should be updated to reflect the behavior of current .NET versions where content equality is what matters.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.text.stringbuilder.equals?view=net-10.0#system-text-stringbuilder-equals(system-text-stringbuilder)

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Text/StringBuilder.xml

Document Version Independent Id

c7e78992-eaf2-dfb2-9b1f-2a2a76297c19

Platform Id

cdcb8c19-bd84-2cd1-1cbf-47c5b6effd16

Article author

@dotnet-bot

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-runtime