docs: add some docs about the bytes interface

src/apply.rs

@@ -100,6 +100,7 @@ pub fn apply(base_image: &str, patch: &Patch<'_, str>) -> Result<String, ApplyEr
     Ok(image.into_iter().map(ImageLine::into_inner).collect())
 }
 
+/// Apply a non-utf8 `Patch` to a base image
 pub fn apply_bytes(base_image: &[u8], patch: &Patch<'_, [u8]>) -> Result<Vec<u8>, ApplyError> {
     let mut image: Vec<_> = LineIter::new(base_image)
         .map(ImageLine::Unpatched)

src/diff/mod.rs

@@ -105,6 +105,7 @@ impl DiffOptions {
         Patch::new("original", "modified", hunks)
     }
 
+    /// Create a patch between two potentially non-utf8 texts
     pub fn create_patch_bytes<'a>(
         &self,
         original: &'a [u8],
@@ -184,6 +185,7 @@ pub fn create_patch<'a>(original: &'a str, modified: &'a str) -> Patch<'a, str>
     DiffOptions::default().create_patch(original, modified)
 }
 
+/// Create a patch between two potentially non-utf8 texts
 pub fn create_patch_bytes<'a>(original: &'a [u8], modified: &'a [u8]) -> Patch<'a, [u8]> {
     DiffOptions::default().create_patch_bytes(original, modified)
 }

src/lib.rs

@@ -10,6 +10,13 @@
 //!
 //! The current diff implementation is based on the [Myers' diff algorithm].
 //!
+//! ## UTF-8 and Non-UTF-8
+//!
+//! This library has support for working with both utf8 and non-utf8 texts.
+//! Most of the API's have two different variants, one for working with utf8
+//! `str` texts (e.g. [`create_patch`]) and one for working with bytes `[u8]`
+//! which may or may not be utf8 (e.g. [`create_patch_bytes`]).
+//!
 //! ## Creating a Patch
 //!
 //! A [`Patch`] between two texts can be created by doing the following:
@@ -202,6 +209,8 @@
 //! [`Display`]: https://doc.rust-lang.org/stable/std/fmt/trait.Display.html
 //! [`Patch`]: struct.Patch.html
 //! [`PatchFormatter`]: struct.PatchFormatter.html
+//! [`create_patch`]: fn.create_patch.html
+//! [`create_patch_bytes`]: fn.create_patch_bytes.html
 
 mod apply;
 mod diff;

src/merge/mod.rs

@@ -175,6 +175,7 @@ impl MergeOptions {
         )
     }
 
+    /// Perform a 3-way merge between potentially non-utf8 texts
     pub fn merge_bytes<'a>(
         &self,
         ancestor: &'a [u8],
@@ -267,6 +268,7 @@ pub fn merge<'a>(ancestor: &'a str, ours: &'a str, theirs: &'a str) -> Result<St
     MergeOptions::default().merge(ancestor, ours, theirs)
 }
 
+/// Perform a 3-way merge between potentially non-utf8 texts
 pub fn merge_bytes<'a>(
     ancestor: &'a [u8],
     ours: &'a [u8],

src/patch/mod.rs

@@ -46,6 +46,10 @@ impl<'a, T: ToOwned + ?Sized> Patch<'a, T> {
 }
 
 impl<T: AsRef<[u8]> + ToOwned + ?Sized> Patch<'_, T> {
+    /// Convert a `Patch` into bytes
+    ///
+    /// This is the equivalent of the `to_string` function but for
+    /// potentially non-utf8 patches.
     pub fn to_bytes(&self) -> Vec<u8> {
         let mut bytes = Vec::new();
         PatchFormatter::new()
@@ -82,6 +86,7 @@ impl<'a> Patch<'a, str> {
 }
 
 impl<'a> Patch<'a, [u8]> {
+    /// Parse a `Patch` from bytes
     pub fn from_bytes(s: &'a [u8]) -> Result<Patch<'a, [u8]>, ParsePatchError> {
         parse::parse_bytes(s)
     }