Documentation updates

src/lib.rs

@@ -2,6 +2,36 @@
 //! interface over different types of diffing algorithms.  It's based on the
 //! the diff algorithm implementations of [pijul](https://pijul.org/).
 //!
+//! The API of the crate is split into high and low level functionality.  Most
+//! of what you probably want to use is available top level.  Additionally the
+//! following sub modules exist:
+//!
+//! * [`algorithms`]: This implements the different types of diffing algorithms.
+//!   It provides both low level access to the algorithms with the minimal
+//!   trait bounds necessary, as well as a generic interface.
+//! * [`udiff`]: Unified diff functionality.
+//!
+//! # Sequence Diffing
+//!
+//! If you want to diff sequences generally indexable things you can use the
+//! [`capture_diff`] and [`capture_diff_slices`] functions.  They will directly
+//! diff an indexable object or slice and return a vector of [`DiffOp`] objects.
+//!
+//! ```rust
+//! use similar::{Algorithm, capture_diff_slices};
+//!
+//! let a = vec![1, 2, 3, 4, 5];
+//! let b = vec![1, 2, 3, 4, 7];
+//! let ops = capture_diff_slices(Algorithm::Myers, &a, &b);
+//! ```
+//!
+//! # Text Diffing
+//!
+//! Similar provides helpful utilities for text (and more specifically line) diff
+//! operations.  The main type you want to work with is [`TextDiff`] which
+//! uses the underlying diff algorithms to expose a convenient API to work with
+//! texts:
+//!
 //! ```rust
 //! # #[cfg(feature = "text")] {
 //! use similar::{ChangeTag, TextDiff};
@@ -24,30 +54,6 @@
 //! # }
 //! ```
 //!
-//! # API
-//!
-//! The API of the crate is split into high and low level functionality.  Most
-//! of what you probably want to use is available toplevel.  Additionally the
-//! following sub modules exist:
-//!
-//! * [`algorithms`]: This implements the different types of diffing algorithms.
-//!   It provides both low level access to the algorithms with the minimal
-//!   trait bounds necessary, as well as a generic interface.
-//! * [`udiff`]: Unified diff functionality.
-//!
-//! # Sequence Diffing
-//!
-//! If you want to diff sequences generally indexable things you can use the
-//! [`capture_diff`] and [`capture_diff_slices`] functions.  They will directly
-//! diff an indexable object or slice and return a vector of [`DiffOp`] objects.
-//!
-//! # Text Diffing
-//!
-//! Similar provides helpful utilities for text (and more specifically line) diff
-//! operations.  The main type you want to work with is [`TextDiff`] which
-//! uses the underlying diff algorithms to expose a convenient API to work with
-//! texts.
-//!
 //! ## Trailing Newlines
 //!
 //! When working with line diffs (and unified diffs in general) there are two
@@ -59,12 +65,15 @@
 //!
 //! In similar this is handled on the [`Change`] or [`InlineChange`] level.  If
 //! a diff was created via [`TextDiff::from_lines`] the text diffing system is
-//! instructed to check if there are missing newlines encountered.  If that is
+//! instructed to check if there are missing newlines encountered
-//! the case the [`Change`] object will return true from the
+//! ([`TextDiff::newline_terminated`] returns true).
-//! [`Change::missing_newline`] method so the caller knows to handle this by
+//!
-//! either rendering a virtual newline at that position or to indicate it in
+//! In any case the [`Change`] object has a convenience method called
-//! different ways.  For instance the unified diff code will render the special
+//! [`Change::missing_newline`] which returns `true` if the change is missing
-//! `\ No newline at end of file` marker.
+//! a trailing newline.  Armed with that information the caller knows to handle
+//! this by either rendering a virtual newline at that position or to indicate
+//! it in different ways.  For instance the unified diff code will render the
+//! special `\ No newline at end of file` marker.
 //!
 //! ## Bytes vs Unicode
 //!
@@ -118,6 +127,7 @@
 //!   in a line diff.  This currently also enables the `unicode` feature.
 #![warn(missing_docs)]
 pub mod algorithms;
+#[cfg(feature = "text")]
 pub mod udiff;
 
 mod common;

src/text/abstraction.rs

@@ -13,6 +13,8 @@ use std::ops::Range;
 ///
 /// This trait is used in the library whenever it's nice to be able to pass
 /// strings of different types in.
+///
+/// Requires the `text` feature.
 pub trait DiffableStrRef {
     /// The type of the resolved [`DiffableStr`].
     type Output: DiffableStr + ?Sized;
@@ -60,6 +62,8 @@ impl DiffableStrRef for Vec<u8> {
 /// on how the crate is compiled.  Out of the box `&str` is always supported
 /// but with the `bytes` feature one can also work with `[u8]` slices for
 /// as long as they are ASCII compatible.
+///
+/// Requires the `text` feature.
 pub trait DiffableStr: Hash + PartialEq + PartialOrd + Ord + Eq + ToOwned {
     /// Splits the value into newlines with newlines attached.
     fn tokenize_lines(&self) -> Vec<&Self>;
@@ -217,6 +221,9 @@ impl DiffableStr for str {
     }
 }
 
+/// Allows viewing ASCII compatible byte slices as strings.
+///
+/// Requires the `bytes` feature.
 #[cfg(feature = "bytes")]
 impl DiffableStr for [u8] {
     fn tokenize_lines(&self) -> Vec<&Self> {

src/text/mod.rs

@@ -17,6 +17,8 @@ use crate::udiff::UnifiedDiff;
 use crate::{capture_diff_slices, get_diff_ratio, group_diff_ops, Algorithm, Change, DiffOp};
 
 /// A builder type config for more complex uses of [`TextDiff`].
+///
+/// Requires the `text` feature.
 #[derive(Clone, Debug)]
 pub struct TextDiffConfig {
     algorithm: Algorithm,
@@ -159,7 +161,9 @@ impl TextDiffConfig {
     }
 }
 
-/// Captures diff op codes for textual diffs
+/// Captures diff op codes for textual diffs.
+///
+/// Requires the `text` feature.
 pub struct TextDiff<'old, 'new, 'bufs, T: DiffableStr + ?Sized> {
     old: Cow<'bufs, [&'old T]>,
     new: Cow<'bufs, [&'new T]>,
@@ -333,6 +337,8 @@ impl<'old, 'new, 'bufs, T: DiffableStr + ?Sized + 'old + 'new> TextDiff<'old, 'n
 /// );
 /// assert_eq!(matches, vec!["apple", "ape"]);
 /// ```
+///
+/// Requires the `text` feature.
 pub fn get_close_matches<'a, T: DiffableStr + ?Sized>(
     word: &T,
     possibilities: &[&'a T],