AK: Add a comment to String about the relationship with StringImpl.

1 files changed, 20 insertions, 0 deletions

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() {}