Repository: mgeisler/textwrap (language: rust)

Issue:
documentation doesn't explain that `termwidth` requires a feature
It should be made much more clear that [termwidth](https://docs.rs/textwrap/0.11.0/textwrap/fn.termwidth.html) is feature flagged.


Discussion / hints:
Right, I see what you mean — when looking at the function alone, there's no warning about the feature flag. I'll update the docstring, thanks!
It's even more confusing because the currently published version (v0.11.0) uses "term_size", but the repo code *Cargo.toml* has "terminal_size". Neither of which is in any published documentation.
😕 
Hi @rivy ! Ups, you have a great point. It seems I painted myself into a bit of a corner when I replaced `term_size` with `terminal_size` in #181...

I had not considered that people would go and look at `Cargo.toml` in the repository — but it's of course the natural place to examine the source code, including the optional features declared in the `Cargo.toml` file.

I guess we could re-introduce the `term_size` feature as an alias for `terminal_size`. In addition, the docstring needs to be updated to make it clear that the function only exists when a certain feature is enabled.

Fix patch:
diff --git a/README.md b/README.md
index d671a98d..72471ba6 100644
--- a/README.md
+++ b/README.md
@@ -19,13 +19,24 @@ To use `textwrap`, add this to your `Cargo.toml` file:
 textwrap = "0.11"
 ```
 
-If you would like to have automatic hyphenation, specify the
-dependency as:
+This gives you the text wrapping without of the optional features
+listed next.
+
+### `hyphenation`
+
+If you would like to have automatic language-sensitive hyphenation,
+enable the `hyphenation` feature:
+
 ```toml
 [dependencies]
 textwrap = { version = "0.11", features = ["hyphenation"] }
 ```
 
+Please see the [`hyphenation` example][hyphenation-example] for how to
+load the hyphenation patterns for your language.
+
+### `terminal_size`
+
 To conveniently wrap text at the current terminal width, enable the
 `terminal_size` feature:
 
@@ -34,6 +45,9 @@ To conveniently wrap text at the current terminal width, enable the
 textwrap = { version = "0.11", features = ["terminal_size"] }
 ```
 
+Please see the [`termwidth` example][termwidth-example] for how to use
+this feature.
+
 ## Documentation
 
 **[API documentation][api-docs]**
@@ -319,6 +333,8 @@ Contributions will be accepted under the same license.
 [appveyor]: https://ci.appveyor.com/project/mgeisler/textwrap
 [codecov]: https://codecov.io/gh/mgeisler/textwrap
 [py-textwrap]: https://docs.python.org/library/textwrap
+[hyphenation-example]: https://github.com/mgeisler/textwrap/blob/master/examples/hyphenation.rs
+[termwidth-example]: https://github.com/mgeisler/textwrap/blob/master/examples/termwidth.rs
 [patterns]: https://github.com/tapeinosyne/hyphenation/tree/master/patterns-tex
 [api-docs]: https://docs.rs/textwrap/
 [rust-2018]: https://doc.rust-lang.org/edition-guide/rust-2018/
diff --git a/src/lib.rs b/src/lib.rs
index 70ddfdaf..0b147094 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -64,7 +64,23 @@
 //! byte count when computing line lengths. All functions in this
 //! library handle Unicode characters like this.
 //!
+//! # Cargo Features
+//!
+//! The library has two optional features:
+//!
+//! * `terminal_size`: enables automatic detection of the terminal
+//!   width via the [terminal_size][] crate. See the
+//!   [`Wrapper::with_termwidth`] constructor for details.
+//!
+//! * `hyphenation`: enables language-sentive hyphenation via the
+//!   [hyphenation][] crate. See the [`WordSplitter`] trait for
+//!   details.
+//!
 //! [unicode-width]: https://docs.rs/unicode-width/
+//! [terminal_size]: https://crates.io/crates/terminal_size
+//! [hyphenation]: https://crates.io/crates/hyphenation
+//! [`Wrapper::with_termwidth`]: struct.Wrapper.html#method.with_termwidth
+//! [`WordSplitter`]: trait.WordSplitter.html
 
 #![doc(html_root_url = "https://docs.rs/textwrap/0.11.0")]
 #![deny(missing_docs)]
@@ -150,6 +166,9 @@ impl<'a> Wrapper<'a, HyphenSplitter> {
     ///
     /// let wrapper = Wrapper::new(termwidth());
     /// ```
+    ///
+    /// **Note:** Only available when the `terminal_size` feature is
+    /// enabled.
     #[cfg(feature = "terminal_size")]
     pub fn with_termwidth() -> Wrapper<'a, HyphenSplitter> {
         Wrapper::new(termwidth())
@@ -634,6 +653,9 @@ impl<'a> WrapIterImpl<'a> {
 ///     .initial_indent("  ")
 ///     .subsequent_indent("  ");
 /// ```
+///
+/// **Note:** Only available when the `terminal_size` feature is
+/// enabled.
 #[cfg(feature = "terminal_size")]
 pub fn termwidth() -> usize {
     terminal_size::terminal_size().map_or(80, |(terminal_size::Width(w), _)| w.into())
diff --git a/src/splitting.rs b/src/splitting.rs
index f6b65afd..3620ef7a 100644
--- a/src/splitting.rs
+++ b/src/splitting.rs
@@ -121,6 +121,9 @@ impl WordSplitter for HyphenSplitter {
 
 /// A hyphenation dictionary can be used to do language-specific
 /// hyphenation using patterns from the hyphenation crate.
+///
+/// **Note:** Only available when the `hyphenation` feature is
+/// enabled.
 #[cfg(feature = "hyphenation")]
 impl WordSplitter for Standard {
     fn split<'w>(&self, word: &'w str) -> Vec<(&'w str, &'w str, &'w str)> {


Test patch: