diff --git a/src/string_width.gleam b/src/string_width.gleam
index a008415..29cd854 100644
--- a/src/string_width.gleam
+++ b/src/string_width.gleam
@@ -121,9 +121,9 @@ pub fn with_tab_width(options: Options, tab_width: Int) -> Options {
 
 /// Define an _offset_ for tab stop calculations. (Default: 0)
 ///
-/// If you do print text not at the first column, but indented by some spaces,
-/// you can set this option to this number to make sure tab stops are correctly
-/// calculated.
+/// If the text you print doesn't start at the first column, but is instead
+/// indented somehow, you can set this option to this number to make sure tab
+/// stops are correctly calculated.
 pub fn at_tab_offset(options: Options, tab_offset: Int) -> Options {
   Options(..options, tab_offset:)
 }
@@ -186,10 +186,10 @@ pub fn line_with(str: String, options: Options) -> Int {
 ///
 /// ```gleam
 /// dimensions("안녕하세요")
-/// // --> #(1, 10)
+/// // --> Size(rows: 1, columns: 10)
 ///
 /// dimensions("hello,\n안녕하세요")
-/// // --> #(2, 10)
+/// // --> Size(rows: 2, columns: 10)
 /// ```
 pub fn dimensions(str: String) -> Size {
   dimensions_with(str, default_options)
@@ -814,7 +814,7 @@ pub type Piece {
 /// Handles tabs and newlines, and always passes full grapheme clusters,
 /// regardless of options. Concatenating the graphemes produces the original string.
 ///
-/// The `with` function is called with `(state, grapheme, width, row, col)`.
+/// Intended to be used as a basis for custom layout algorithms.
 pub fn fold(
   over str: String,
   from state: state,
@@ -828,7 +828,7 @@ pub fn fold(
 /// Handles tabs and newlines, and always passes full grapheme clusters,
 /// regardless of options. Concatenating the graphemes produces the original string.
 ///
-/// The `with` function is called with `(state, grapheme, width, row, col)`.
+/// Intended to be used as a basis for custom layout algorithms.
 pub fn fold_with(
   over str: String,
   using options: Options,
@@ -874,14 +874,15 @@ pub fn fold_with(
   state
 }
 
-/// Iterate over the measured components of a string. Components are either
-/// graphemes or codepoints, depending on the `mode` option,
+/// A low-level fold that iterate over the measured components of a string.
+/// Components are either graphemes or codepoints depending on the `mode` option,
 /// or other undivisible sequences, like ANSI escape codes.
 ///
-/// This is a lower-level utility compared to the others in this package. It does
-/// not by itself keep track of any additional state, and does not for example
-/// handle newlines or tabs. Instead, you can use fold to implement all kinds of
-/// higher-level layout primitives.
+/// This function does not by itself keep track of any additional state, and
+/// doesn't for example handle newlines or tabs like `fold` would.
+/// If you know that your algorithm is safe and won't break up graphemes (or
+/// maybe this is acceptable), you can use this fold variant instead as a
+/// performance optimisation.
 ///
 /// Concatenating all components is guaranteed to produce the original string.
 ///