Merge pull request #437 from mgeisler/test-readme-examples

Make README examples testable

Cargo.toml

@@ -48,7 +48,6 @@ criterion = "0.3.5"
 lipsum = "0.8.0"
 unic-emoji-char = "0.9.0"
 version-sync = "0.9.4"
-doc-comment = "0.3.3"
 
 [target.'cfg(unix)'.dev-dependencies]
 termion = "1.5.6"

README.md

@@ -36,38 +36,47 @@ your binary.
 
 ## Getting Started
 
-Word wrapping is easy using the `fill` function:
+Word wrapping is easy using the `wrap` and `fill` functions:
 
 ```rust
-fn main() {
-    let text = "textwrap: an efficient and powerful library for wrapping text.";
-    println!("{}", textwrap::fill(text, 28));
+#[cfg(feature = "smawk")] {
+let text = "textwrap: an efficient and powerful library for wrapping text.";
+assert_eq!(
+    textwrap::wrap(text, 28),
+    vec![
+        "textwrap: an efficient",
+        "and powerful library for",
+        "wrapping text.",
+    ]
+);
 }
 ```
 
-The output is wrapped within 28 columns:
-
-```text
-textwrap: an efficient
-and powerful library for
-wrapping text.
-```
-
 Sharp-eyed readers will notice that the first line is 22 columns wide.
 So why is the word “and” put in the second line when there is space
 for it in the first line?
 
 The explanation is that textwrap does not just wrap text one line at a
 time. Instead, it uses an optimal-fit algorithm which looks ahead and
 chooses line breaks which minimize the gaps left at ends of lines.
+This is controlled with the `smawk` Cargo feature, which is why the
+example is wrapped in the `cfg`-block.
 
 Without look-ahead, the first line would be longer and the text would
 look like this:
 
-```text
-textwrap: an efficient and
-powerful library for
-wrapping text.
+```rust
+#[cfg(not(feature = "smawk"))] {
+let text = "textwrap: an efficient and powerful library for wrapping text.";
+assert_eq!(
+    textwrap::wrap(text, 28),
+    vec![
+        "textwrap: an efficient and",
+        "powerful library for",
+        "wrapping text.",
+    ]
+);
+}
 ```
 
 The second line is now shorter and the text is more ragged. The kind
@@ -81,25 +90,24 @@ Your program must load the hyphenation pattern and configure
 `Options::word_splitter` to use it:
 
 ```rust
+#[cfg(feature = "hyphenation")] {
 use hyphenation::{Language, Load, Standard};
-use textwrap::{fill, Options};
 
-fn main() {
-    let hyphenator = Standard::from_embedded(Language::EnglishUS).unwrap();
-    let options = Options::new(28).word_splitter(hyphenator);
-    let text = "textwrap: an efficient and powerful library for wrapping text.";
-    println!("{}", fill(text, &options));
+let hyphenator = Standard::from_embedded(Language::EnglishUS).unwrap();
+let options = textwrap::Options::new(28).word_splitter(hyphenator);
+let text = "textwrap: an efficient and powerful library for wrapping text.";
+
+assert_eq!(
+    textwrap::wrap(text, &options),
+    vec![
+        "textwrap: an efficient and",
+        "powerful library for wrap-",
+        "ping text."
+    ]
+);
 }
 ```
 
-The output now looks like this:
-
-```text
-textwrap: an efficient and
-powerful library for wrap-
-ping text.
-```
-
 The US-English hyphenation patterns are embedded when you enable the
 `hyphenation` feature. They are licensed under a [permissive
 license][en-us license] and take up about 88 KB in your binary. If you

src/lib.rs

@@ -195,8 +195,10 @@
 #![deny(missing_debug_implementations)]
 #![allow(clippy::redundant_field_names)]
 
-#[cfg(all(doctest, feature = "hyphenation"))]
-doc_comment::doctest!("../README.md", readme_doctest);
+// Make `cargo test` execute the README doctests.
+#[cfg(doctest)]
+#[doc = include_str!("../README.md")]
+mod readme_doctest {}
 
 use std::borrow::Cow;