Clarify use

2 files changed, 21 insertions, 14 deletions

diff --git a/src/gleam/bytes_builder.gleam b/src/gleam/bytes_builder.gleam
index 20c145d..2b36f9c 100644
--- a/src/gleam/bytes_builder.gleam
+++ b/src/gleam/bytes_builder.gleam
@@ -1,9 +1,13 @@
-//// BytesBuilder is a type used for efficiently concatenating bytes together
-//// without copying.
+//// `BytesBuilder` is a type used for efficiently building text content to be
+//// written to a file or a socket. Internally it is represented as tree so to
+//// append or prepend to a bytes builder is a constant time operation that
+//// allocates a new node in the tree without copying any of the content. When
+//// writing to an output stream the tree is traversed and the content is sent
+//// directly rather than copying it into a single buffer beforehand.
 ////
 //// If we append one bit array to another the bit arrays must be copied to a
 //// new location in memory so that they can sit together. This behaviour
-//// enables efficient reading of the string but copying can be expensive,
+//// enables efficient reading of the data but copying can be expensive,
 //// especially if we want to join many bit arrays together.
 ////
 //// BytesBuilder is different in that it can be joined together in constant
@@ -17,8 +21,9 @@
 
 // TODO: pad bit arrays to byte boundaries when adding to a builder.
 import gleam/string_builder.{type StringBuilder}
-import gleam/list
+
 import gleam/bit_array
+import gleam/list
 
 pub opaque type BytesBuilder {
   Bytes(BitArray)
diff --git a/src/gleam/string_builder.gleam b/src/gleam/string_builder.gleam
index 960a36f..8415097 100644
--- a/src/gleam/string_builder.gleam
+++ b/src/gleam/string_builder.gleam
@@ -1,19 +1,21 @@
 import gleam/list
 
-/// `StringBuilder` is a type used for efficiently building strings.
-///
-/// When we append one string to another the strings must be copied to a
-/// new location in memory so that they can sit together. This behaviour
-/// enables efficient reading of the string but copying can be expensive,
-/// especially if we want to join many strings together.
-///
-/// `StringBuilder` is different in that it can be joined together in constant time
-/// using minimal memory, and then can be efficiently converted to a string
-/// using the `to_string` function.
+/// `StringBuilder` is a type used for efficiently building text content to be
+/// written to a file or a socket. Internally it is represented as tree so to
+/// append or prepend to a string builder is a constant time operation that
+/// allocates a new node in the tree without copying any of the content. When
+/// writing to an output stream the tree is traversed and the content is sent
+/// directly rather than copying it into a single buffer beforehand.
 ///
 /// On Erlang this type is compatible with Erlang's iodata. On JavaScript this
 /// type is compatible with normal strings.
 ///
+/// The BEAM virtual machine has an optimisation for appending strings, where it
+/// will mutate the string buffer when safe to do so, so if you are looking to
+/// build a string through appending many small strings then you may get better
+/// performance by not using a string builder. Always benchmark your performance
+/// sensitive code.
+///
 pub type StringBuilder
 
 /// Create an empty `StringBuilder`. Useful as the start of a pipe chaining many