From b658699fac944d78d7bb13b16d24c0d8b922cfd0 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..52f69bcbf12 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, `clear`ing a StringBuf
+		MAY not reallocate the internal buffer, 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 = "";