docs: add comprehensive DocC documentation for all three library products

Add DocC catalogs with landing pages for TextBuffer, TextRope, and
TextBufferTesting. Create "Choosing a Buffer" and "Undo and Redo"
article pages with decision tables and code examples. Add doc comments
to all previously undocumented public types. Update MutableStringBuffer
docs to point to SendableRopeBuffer as the recommended in-memory buffer.

Author: claude

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+### Added
+
+- DocC documentation for all three library products: TextBuffer, TextRope, and TextBufferTesting each have a DocC catalog with a landing page and organized topic groups.
+- "Choosing a Buffer" article — decision guide with comparison table and code examples, positioning `SendableRopeBuffer` as the recommended in-memory buffer.
+- "Undo and Redo" article — explains both `UndoManager`-based and `OperationLog`-based strategies with code examples.
+- Doc comments for previously undocumented public types: `TextBuffer` protocol, `RopeBuffer`, `SendableRopeBuffer`, `TransferableUndoable`, `PuppetUndoManager`, `OperationLog`, `UndoGroup`, `BufferOperation`, `BufferContent`, `TextRope`, and all TextBufferTesting helpers.
+
 ### Changed
 
 - **BREAKING:** `InMemoryBuffer` typealias now points to `SendableRopeBuffer` (was `MutableStringBuffer`). The rope-backed, `Sendable` value type with built-in undo is the proper in-memory buffer for production use. `MutableStringBuffer` remains available by its concrete name.

Sources/TextBuffer/Buffer/BufferContent.swift

@@ -1,5 +1,9 @@
 //  Copyright © 2024 Christian Tietze. All rights reserved. Distributed under the MIT License.
 
+/// A type whose instances can report their length, used by buffer protocols to measure content.
+///
+/// `String` conforms to `BufferContent` with its `length` returning `utf16.count`,
+/// matching Foundation's `NSString` indexing used throughout the buffer API.
 public protocol BufferContent<Length> {
     associatedtype Length
     var length: Length { get }

Sources/TextBuffer/Buffer/MutableStringBuffer.swift

@@ -2,16 +2,13 @@
 
 import Foundation
 
-/// A self-contained ``Buffer`` implementation, backed by `NSMutableString` as the UTF-16-offset indexed storage.
+/// A ``Buffer`` implementation backed by `NSMutableString` as the UTF-16-offset indexed storage.
 ///
-/// Used as in-memory buffers, you can apply changes to off-screen textual content in a way that is consistent with text views, but actually independent of these. Opposed to the platform's Text Kit views, which are large class clusters with a lot of automatic behavior pertaining layout, keeping a ``MutableStringBuffer`` in memory produces little overhead. (In fact, only as much overhead as a `NSMutableString` will, plus storing the selected range.)
+/// `MutableStringBuffer` is a lightweight reference-type buffer useful for simple tests and for
+/// copying snapshots of other buffers. For general-purpose in-memory text manipulation,
+/// prefer ``SendableRopeBuffer``, which offers O(log n) mutations, built-in undo, and `Sendable` safety.
 ///
-/// To adapt other buffers and copy their content, use ``MutableStringBuffer/init(copying:)``.
-///
-/// ## Utility for Apps
-///
-/// - Use ``MutableStringBuffer`` in unit tests.
-/// - Maintain multiple text buffers in memory while only ever rendering one buffer as a text view on screen, e.g. for opening multiple files in your app.
+/// To copy another buffer's content, use ``MutableStringBuffer/init(copying:)``.
 public final class MutableStringBuffer: Buffer, TextAnalysisCapable {
     public typealias Range = NSRange
     public typealias Content = String

Sources/TextBuffer/Buffer/PuppetUndoManager.swift

@@ -10,6 +10,11 @@ protocol PuppetUndoManagerDelegate: AnyObject {
     var puppetRedoActionName: String { get }
 }
 
+/// An `UndoManager` subclass that delegates undo and redo to a ``TransferableUndoable``'s ``OperationLog``.
+///
+/// You don't create instances directly. Instead, call
+/// ``TransferableUndoable/enableSystemUndoIntegration()`` to obtain one. Assign the returned
+/// undo manager to your window or document to enable AppKit's Edit menu undo/redo items.
 @MainActor
 public final class PuppetUndoManager: UndoManager {
     weak var owner: (any PuppetUndoManagerDelegate)?

Sources/TextBuffer/Buffer/RopeBuffer.swift

@@ -1,6 +1,18 @@
 import Foundation
 import TextRope
 
+/// A ``Buffer`` implementation backed by a ``TextRope`` for efficient manipulation of large texts.
+///
+/// `RopeBuffer` provides O(log n) insert, delete, and replace operations, making it a better choice
+/// than ``MutableStringBuffer`` when working with very large documents.
+///
+/// `RopeBuffer` is a reference type and is **not** `Sendable`. For a thread-safe value-type alternative,
+/// use ``SendableRopeBuffer``.
+///
+/// `RopeBuffer` does not include built-in undo support. Wrap it in ``Undoable`` or ``TransferableUndoable``
+/// to add undo/redo.
+///
+/// To copy another buffer's content, use ``init(copying:)``.
 public final class RopeBuffer: Buffer, TextAnalysisCapable {
     public typealias Range = NSRange
     public typealias Content = String

Sources/TextBuffer/Buffer/TextBuffer.swift

@@ -1,3 +1,11 @@
+/// Synchronous text buffer protocol for value types.
+///
+/// ``TextBuffer`` is the counterpart to ``Buffer`` (which targets reference types and refines ``AsyncBuffer``).
+/// Both protocols expose the same API surface — content access, selection management, and text mutations —
+/// but ``TextBuffer`` uses `mutating` methods, making it suitable for structs like ``SendableRopeBuffer``.
+///
+/// The primary associated type is `Range`, which determines the range representation.
+/// `Location` is derived as `Range.Position`.
 public protocol TextBuffer<Range> {
     associatedtype Range: BufferRange
     typealias Location = Range.Position

Sources/TextBuffer/Buffer/TransferableUndoable.swift

@@ -1,5 +1,22 @@
 import Foundation
 
+/// Decorator of any ``Buffer`` to add undo/redo functionality through an ``OperationLog``.
+///
+/// Unlike ``Undoable``, which relies on Foundation's `UndoManager`, `TransferableUndoable` records
+/// all mutations as ``BufferOperation`` values for replay-based undo. This makes the undo history
+/// inspectable, serializable, and transferable between buffer instances.
+///
+/// ## Snapshots and State Transfer
+///
+/// - ``snapshot()`` captures the current content, selection, and operation log as a new
+///   `TransferableUndoable<MutableStringBuffer>`.
+/// - ``sendableSnapshot()`` produces a ``SendableRopeBuffer`` that can cross actor boundaries.
+/// - `represent(_:)` restores state from another `TransferableUndoable` or a ``SendableRopeBuffer``.
+///
+/// ## System Undo Integration
+///
+/// Call ``enableSystemUndoIntegration()`` to obtain an `UndoManager` that bridges to this buffer's
+/// ``OperationLog``, enabling AppKit undo menu items and the responder chain.
 @MainActor
 public final class TransferableUndoable<Base>: @MainActor Buffer where Base: Buffer, Base.Range == NSRange, Base.Content == String {
     public typealias Range = NSRange

Sources/TextBuffer/Documentation.docc/ChoosingABuffer.md

@@ -0,0 +1,102 @@
+# Choosing a Buffer
+
+Pick the right buffer implementation for your use case.
+
+## Overview
+
+The TextBuffer library provides several concrete buffer types that all share the same read-and-mutate API.
+They differ in backing storage, value vs. reference semantics, `Sendable` conformance, and built-in undo support.
+
+For most use cases, ``SendableRopeBuffer`` (aliased as `InMemoryBuffer`) is the recommended starting point:
+it's a `Sendable` value type with efficient rope-backed storage, built-in undo/redo, and O(log n) mutations
+that scale to large documents.
+
+## At a Glance
+
+| Type | Backing | Semantics | Built-in Undo | Sendable | Best for |
+|------|---------|-----------|---------------|----------|----------|
+| ``SendableRopeBuffer`` | ``TextRope`` | value | ``OperationLog`` | yes | general-purpose in-memory buffer |
+| ``MutableStringBuffer`` | `NSMutableString` | reference | no | no | simple tests |
+| ``RopeBuffer`` | ``TextRope`` | reference | no | no | reference-type rope without undo |
+| ``NSTextViewBuffer`` | `NSTextView` | reference, `@MainActor` | no | no | driving an AppKit text view |
+
+All four conform to ``TextAnalysisCapable``, so you get ``TextAnalysisCapable/wordRange(for:)``
+and ``TextAnalysisCapable/lineRange(for:)`` on every buffer.
+
+## The In-Memory Buffer: SendableRopeBuffer
+
+``SendableRopeBuffer`` is the default choice for in-memory text manipulation. It combines:
+
+- **Efficient storage** via ``TextRope`` — O(log n) insert, delete, and replace, even for large documents.
+- **Built-in undo/redo** via ``OperationLog`` — no decorator needed.
+- **Value semantics and `Sendable`** — safe to pass across actor boundaries.
+
+```swift
+var buffer = SendableRopeBuffer("Hello, World!")
+try buffer.insert("!", at: 13)
+print(buffer.content) // "Hello, World!!"
+
+buffer.undo()
+print(buffer.content) // "Hello, World!"
+```
+
+For apps that need a reference-type buffer with `UndoManager` integration or snapshot/transfer
+capabilities, wrap a ``RopeBuffer`` in ``TransferableUndoable`` (aliased as `EditingBuffer`):
+
+```swift
+let editing = TransferableUndoable(RopeBuffer("Document text"))
+```
+
+## Other Buffer Types
+
+``MutableStringBuffer`` is backed by `NSMutableString`. It's lightweight and useful in simple tests,
+but its O(n) mutations don't scale to large texts. It has no built-in undo — wrap it in
+``Undoable`` or ``TransferableUndoable`` if needed.
+
+``RopeBuffer`` gives you rope-backed O(log n) performance as a reference type, but without built-in undo.
+Use it when you need a mutable reference-type buffer to wrap in ``Undoable`` or ``TransferableUndoable``.
+
+``NSTextViewBuffer`` adapts an `NSTextView` for use through the buffer API. All mutations go through
+`NSTextStorage` wrapped in `beginEditing()`/`endEditing()`. It's `@MainActor`-isolated.
+
+```swift
+let textViewBuffer = NSTextViewBuffer(textView: myTextView)
+try textViewBuffer.replace(range: textViewBuffer.selectedRange, with: "replacement")
+```
+
+## Writing Generic Code
+
+Constrain on ``Buffer`` for reference-type buffers (classes) or ``TextBuffer`` for value-type buffers (structs).
+Use ``TextAnalysisCapable`` when you need word or line analysis.
+
+```swift
+func wordAtInsertion<B: Buffer>(in buffer: B) throws -> String
+where B.Range == NSRange, B.Content == String, B: TextAnalysisCapable {
+    let word = try buffer.wordRange(for: buffer.selectedRange)
+    return try buffer.content(in: word)
+}
+```
+
+## Copying Between Buffer Types
+
+Every buffer can be copied into a ``MutableStringBuffer`` or ``RopeBuffer`` via `init(copying:)`:
+
+```swift
+let copy = MutableStringBuffer(copying: someBuffer)
+let ropeCopy = RopeBuffer(copying: someBuffer)
+```
+
+For crossing actor boundaries, ``TransferableUndoable`` provides ``TransferableUndoable/sendableSnapshot()``
+to produce a ``SendableRopeBuffer``, and ``TransferableUndoable/represent(_:)-(SendableRopeBuffer)`` to restore
+from one:
+
+```swift
+// On @MainActor
+let snapshot = transferableBuffer.sendableSnapshot()
+
+// On another actor / in a Task
+await process(snapshot)
+
+// Back on @MainActor
+transferableBuffer.represent(snapshot)
+```

Sources/TextBuffer/Documentation.docc/Documentation.md

@@ -4,23 +4,50 @@ Text buffer abstractions to power your text editor, in UI or in memory.
 
 ## Overview
 
-To simulate modifications and insertion point movement or selection changes in text views, you need to create the actual UI component. This is both rather resource intensive and constrained to the `MainActor`.
+TextBuffer provides a uniform API for reading, mutating, and selecting text — whether backed by
+an `NSMutableString`, a rope, or an `NSTextView`. All buffers share the same operations: access
+content, manage a selection or insertion point, and insert, delete, or replace text.
 
-With in-memory buffers, you get the same behavior, but without the UI overhead.
+The library defines two parallel protocol hierarchies. ``Buffer`` (which refines ``AsyncBuffer``)
+targets reference-type conformers like ``MutableStringBuffer``, ``RopeBuffer``, and
+``NSTextViewBuffer``. ``TextBuffer`` targets value types like ``SendableRopeBuffer``.
+Both hierarchies expose the same API surface; ``TextAnalysisCapable`` adds word and line range
+analysis to either.
 
 ## Topics
 
-### Buffers
+### Essentials
 
-A `Buffer` is an abstraction of textual content and a selection.
+- <doc:ChoosingABuffer>
+- <doc:UndoAndRedo>
+
+### Protocols
 
 - ``Buffer``
-- ``MutableStringBuffer``
-- ``Undoable``
+- ``TextBuffer``
+- ``AsyncBuffer``
+- ``TextAnalysisCapable``
+- ``BufferRange``
+- ``BufferContent``
 
-### Platform-Specific Buffer Adapters
+### In-Memory Buffers
+
+- ``MutableStringBuffer``
+- ``RopeBuffer``
+- ``SendableRopeBuffer``
 
-Text Kit's text views behave as buffers, but offer a much wider surface API to perform layout and typesetting. Opposed to these, a `Buffer` is a lightweight API to perform changes like a user would in an interactive text view, which we expose as adapters.
+### Platform Adapters
 
 - ``NSTextViewBuffer``
 
+### Undo Support
+
+- ``Undoable``
+- ``TransferableUndoable``
+- ``OperationLog``
+- ``UndoGroup``
+- ``BufferOperation``
+
+### Error Handling
+
+- ``BufferAccessFailure``

Sources/TextBuffer/Documentation.docc/UndoAndRedo.md

@@ -0,0 +1,103 @@
+# Undo and Redo
+
+Add undo/redo to your buffers using UndoManager or OperationLog.
+
+## Overview
+
+TextBuffer offers two undo strategies. Choose based on whether you need AppKit `UndoManager` integration
+or a portable, `Sendable` undo history.
+
+## UndoManager-Based: Undoable
+
+``Undoable`` is a decorator that wraps any ``Buffer`` and registers inverse actions with Foundation's
+`UndoManager`. It integrates directly with AppKit's Edit menu and the responder chain.
+
+```swift
+let buffer = MutableStringBuffer("Hello")
+let undoable = Undoable(buffer)
+
+undoable.undoGrouping(actionName: "Greet") {
+    try! undoable.delete(in: undoable.range)
+    try! undoable.insert("Hi, World!")
+}
+print(buffer.content) // "Hi, World!"
+
+undoable.undo()
+print(buffer.content) // "Hello"
+
+undoable.redo()
+print(buffer.content) // "Hi, World!"
+```
+
+> Warning: You must keep the ``Undoable`` instance alive for undo to work.
+> It removes all registered undo actions from its ``Undoable/undoManager`` on deinitialization
+> to avoid crashes from dangling `unowned` references.
+
+## OperationLog-Based: TransferableUndoable and SendableRopeBuffer
+
+``OperationLog`` records each mutation as a ``BufferOperation`` value. Undo and redo work by
+replaying operations in reverse or forward order. This makes the history inspectable,
+serializable, and transferable.
+
+### TransferableUndoable
+
+``TransferableUndoable`` is a decorator like ``Undoable``, but backed by ``OperationLog``
+instead of `UndoManager`. It supports snapshotting and state transfer:
+
+```swift
+let base = RopeBuffer("Document text")
+let buffer = TransferableUndoable(base)
+
+buffer.undoGrouping(actionName: "Edit") {
+    try! buffer.replace(range: NSRange(location: 0, length: 8), with: "New")
+}
+
+// Snapshot for transfer across actors
+let snapshot = buffer.sendableSnapshot()
+
+// Restore from snapshot
+buffer.represent(snapshot)
+
+// Bridge to system undo for AppKit menus
+let undoManager = buffer.enableSystemUndoIntegration()
+myWindow.undoManager = undoManager
+```
+
+### SendableRopeBuffer
+
+``SendableRopeBuffer`` is a `Sendable` value type with ``OperationLog`` built in.
+No decorator needed — undo/redo is part of the buffer itself:
+
+```swift
+var buffer = SendableRopeBuffer("Hello")
+try buffer.insert(", World", at: 5)
+
+buffer.undoGrouping(actionName: "Replace") { buf in
+    try! buf.delete(in: buf.range)
+    try! buf.insert("Goodbye")
+}
+print(buffer.content) // "Goodbye"
+
+buffer.undo()
+print(buffer.content) // "Hello, World"
+
+buffer.redo()
+print(buffer.content) // "Goodbye"
+```
+
+## Choosing an Undo Strategy
+
+| Strategy | Type | Sendable | AppKit Integration | Snapshots |
+|----------|------|----------|--------------------|-----------|
+| `UndoManager` | ``Undoable`` | no | built-in | no |
+| `OperationLog` | ``TransferableUndoable`` | no (but can snapshot) | via ``TransferableUndoable/enableSystemUndoIntegration()`` | yes |
+| `OperationLog` | ``SendableRopeBuffer`` | yes | no | is the snapshot |
+
+Use ``Undoable`` when you already have an `UndoManager` (e.g., document-based apps) and want
+zero-configuration AppKit integration.
+
+Use ``TransferableUndoable`` when you need to snapshot buffer state, transfer it across actors,
+or want an inspectable operation history while still wrapping a reference-type buffer.
+
+Use ``SendableRopeBuffer`` when you need a fully self-contained, `Sendable` buffer with undo —
+for example, in background processing or when the buffer itself crosses isolation boundaries.