Document splitting pipeline

src/core.rs

@@ -3,6 +3,32 @@
 //! The functions and structs in this module can be used to implement
 //! advanced wrapping functionality when the [`wrap`](super::wrap) and
 //! [`fill`](super::fill) function don't do what you want.
+//!
+//! In general, you want to follow these steps when wrapping
+//! something:
+//!
+//! 1. Split your input into [`Fragment`]s. These are abstract blocks
+//!    of text or content which can be wrapped into lines. You can use
+//!    [`find_words`] to do this for text.
+//!
+//! 2. Potentially split your fragments into smaller pieces. This
+//!    allows you to implement things like hyphenation. If wrapping
+//!    text, [`split_words`] can help you do this.
+//!
+//! 3. Potentially break apart fragments that are still too large to
+//!    fit on a single line. This is implemented in [`break_words`].
+//!
+//! 4. Finally take your fragments and put them into lines. There are
+//!    two algorithms for this: [`wrap_optimal_fit`] and
+//!    [`wrap_first_fit`]. The former produces better line breaks, the
+//!    latter is faster.
+//!
+//! 5. Iterate through the slices returned by the wrapping functions
+//!    and construct your lines of output.
+//!
+//! Please [open an issue](https://github.com/mgeisler/textwrap/) if
+//! the functionality here is not sufficient or if you have ideas for
+//! improving it. We would love to hear from you!
 
 use crate::{Options, WordSplitter};
 use std::cell::RefCell;