Improve the documentation.

Author: artob

README.md

@@ -12,8 +12,8 @@
 - Provides the [`Tldr`](#tldr) trait for generating TL;DR summaries.
 - Provides the [`ToTldr`](#totldr) trait for converting objects into TL;DR
   summaries.
-- Supports TL;DR generation for multiple natural languages.
-- Zero required dependencies, only optional integrations.
+- Supports multilingual TL;DR generation while defaulting to English.
+- Zero required dependencies, only optional integrations with [Serde] & [Bon].
 - Adheres to the Rust API Guidelines in its [naming conventions].
 - 100% free and unencumbered public domain software.
 
@@ -153,7 +153,9 @@ git clone https://github.com/dryrust/tldr.rs.git
 [![Share on Facebook](https://img.shields.io/badge/share%20on-fb-1976D2?logo=facebook)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/dryrust/tldr.rs)
 [![Share on LinkedIn](https://img.shields.io/badge/share%20on-linkedin-3949AB?logo=linkedin)](https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/dryrust/tldr.rs)
 
+[Bon]: https://crates.io/crates/bon
 [Rust]: https://rust-lang.org
+[Serde]: https://crates.io/crates/serde
 [TL;DR]: https://en.wikipedia.org/wiki/TL;DR
 [five Ws]: https://en.wikipedia.org/wiki/Five_Ws
 [naming conventions]: https://rust-lang.github.io/api-guidelines/naming.html

src/context.rs

@@ -3,12 +3,17 @@
 use crate::TldrLanguage;
 use core::str::FromStr;
 
+/// A context used when generating TL;DR summaries.
+///
+/// # Examples
+///
 /// ```rust
 /// # use tldr_traits::TldrContext;
 /// let context = TldrContext::builder()
 ///     .language("en")
 ///     .build();
 /// ```
+#[non_exhaustive]
 #[derive(Clone, Debug, Default, Eq, Hash, PartialEq)]
 #[cfg_attr(feature = "builder", derive(bon::Builder))]
 #[cfg_attr(feature = "builder", builder(on(TldrLanguage, into)))]

src/language.rs

@@ -3,6 +3,10 @@
 use alloc::string::String;
 use core::{fmt, str::FromStr};
 
+/// The language that a TL;DR summary is written in.
+///
+/// # Examples
+///
 /// ```rust
 /// # use tldr_traits::TldrLanguage;
 /// let language = TldrLanguage::default(); // this is the same as...

src/result.rs

@@ -3,4 +3,5 @@
 use alloc::{boxed::Box, string::String};
 use core::error::Error;
 
+/// The result type used throughout the library.
 pub type TldrResult<T = String, E = Box<dyn Error>> = Result<Option<T>, E>;

src/summary.rs

@@ -4,6 +4,10 @@ use crate::{Tldr, TldrContext, TldrResult, ToTldr};
 use alloc::{boxed::Box, string::String};
 use core::fmt::Debug;
 
+/// An owned TL;DR summary.
+///
+/// # Examples
+///
 /// ```rust
 /// # use tldr_traits::TldrSummary;
 /// let summary: TldrSummary<String> = TldrSummary::builder()
@@ -17,8 +21,9 @@ use core::fmt::Debug;
 ///     .build();
 /// ```
 ///
-/// See: https://en.wikipedia.org/wiki/Five_Ws
-/// See: https://en.wikipedia.org/wiki/Interrogative_word
+/// See: [en.wikipedia.org/wiki/Five_Ws](https://en.wikipedia.org/wiki/Five_Ws)
+///
+/// See: [en.wikipedia.org/wiki/Interrogative_word](https://en.wikipedia.org/wiki/Interrogative_word)
 #[derive(Clone, Debug, Default)]
 #[cfg_attr(feature = "builder", derive(bon::Builder))]
 #[cfg_attr(feature = "builder", builder(on(T, into)))]

src/traits/tldr.rs

@@ -3,6 +3,12 @@
 use crate::{TldrContext, TldrResult};
 use alloc::string::String;
 
+/// A trait for generating a TL;DR summary.
+///
+/// # Examples
+///
+/// Implementing the `Tldr` trait for a custom type is simple:
+///
 /// ```rust
 /// # use tldr_traits::{Tldr, TldrContext, TldrResult};
 /// # use core::error::Error;
@@ -20,8 +26,33 @@ use alloc::string::String;
 /// }
 /// ```
 ///
-/// See: https://en.wikipedia.org/wiki/Five_Ws
-/// See: https://en.wikipedia.org/wiki/Interrogative_word
+/// Generally, you'd want to match on the context language to provide a
+/// localized response:
+///
+/// ```rust
+/// # use tldr_traits::{Tldr, TldrContext, TldrLanguage, TldrResult};
+/// # use core::error::Error;
+/// struct Rectangle {
+///     width: u32,
+///     height: u32,
+/// }
+///
+/// impl Tldr<String> for Rectangle {
+///     type Error = Box<dyn Error>;
+///
+///     fn what(&self, ctx: &TldrContext) -> TldrResult<String> {
+///         use TldrLanguage::*;
+///         Ok(match ctx.language {
+///             English => Some(format!("A rectangle with a width of {} and a height of {}.", self.width, self.height)),
+///             _ => None,
+///         })
+///     }
+/// }
+/// ```
+///
+/// See: [en.wikipedia.org/wiki/Five_Ws](https://en.wikipedia.org/wiki/Five_Ws)
+///
+/// See: [en.wikipedia.org/wiki/Interrogative_word](https://en.wikipedia.org/wiki/Interrogative_word)
 pub trait Tldr<T = String> {
     /// The associated error type.
     ///

src/traits/to_tldr.rs

@@ -3,6 +3,10 @@
 use crate::Tldr;
 use alloc::{boxed::Box, string::String};
 
+/// A trait for converting objects into TL;DR summaries.
+///
+/// # Examples
+///
 /// ```rust
 /// # use tldr_traits::{Tldr, TldrSummary, ToTldr};
 /// struct Rectangle {