From e24f18dd83837e52cc7be17cfe7dfa8c932b001c Mon Sep 17 00:00:00 2001
From: Andreas Kling <awesomekling@gmail.com>
Date: Sun, 2 Jun 2019 08:37:01 +0200
Subject: [PATCH] AK: Add a comment to String about the relationship with
 StringImpl.

---
 AK/AKString.h | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/AK/AKString.h b/AK/AKString.h
index b93843b719..a2a972ebf9 100644
--- a/AK/AKString.h
+++ b/AK/AKString.h
@@ -10,6 +10,26 @@
 
 namespace AK {
 
+// String is a convenience wrapper around StringImpl, suitable for passing
+// around as a value type. It's basically the same as passing around a
+// RetainPtr<StringImpl>, with a bit of syntactic sugar.
+//
+// Note that StringImpl is an immutable object that cannot shrink or grow.
+// Its allocation size is snugly tailored to the specific string it contains.
+// Copying a String is very efficient, since the internal StringImpl is
+// retainable and so copying only requires modifying the retain count.
+//
+// There are three main ways to construct a new String:
+//
+//     s = String("some literal");
+//
+//     s = String::format("%d little piggies", m_piggies);
+//
+//     StringBuilder builder;
+//     builder.append("abc");
+//     builder.append("123");
+//     s = builder.to_string();
+
 class String {
 public:
     ~String() {}