From eb20fac17108ae2b227c374bce9ea3cc9d1a03e0 Mon Sep 17 00:00:00 2001
From: Frixuu <kontakt@lukasz.xyz>
Date: Wed, 4 Dec 2024 10:04:08 +0100
Subject: [PATCH] [std] Clarify StringBuf.clear documentation

---
 std/StringBuf.hx | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/std/StringBuf.hx b/std/StringBuf.hx
index 6cbc140f533..2eda6ba0f2d 100644
--- a/std/StringBuf.hx
+++ b/std/StringBuf.hx
@@ -89,9 +89,12 @@ class StringBuf {
 	}
 
 	/**
-		Removes all characters from `this` StringBuf, making it possible to reuse it.
+		Visibly removes all characters from `this` StringBuf, making it possible to reuse it.
 
-		It will always allocate less memory than constructing a new `StringBuf` instance.
+		Implementation detail: On some targets, where `this` StringBuf manages an internal buffer,
+		that buffer MAY not be reallocated on `clear`, preserving its capacity.
+		This is done to avoid unnecessary allocations on later `add` operations,
+		but might be incorrectly perceived as a memory leak.
 	**/
 	public inline function clear():Void {
 		b = "";