document Offset (#1752)

src/error.rs

@@ -299,6 +299,9 @@ where
 }
 
 /// Transforms a `VerboseError` into a trace with input position information
+///
+/// The errors contain references to input data that must come from `input`,
+/// because nom calculates byte offsets between them
 #[cfg(feature = "alloc")]
 #[cfg_attr(feature = "docsrs", doc(cfg(feature = "alloc")))]
 pub fn convert_error<I: core::ops::Deref<Target = str>>(

src/traits.rs

@@ -568,6 +568,8 @@ impl<'a> Input for &'a str {
 /// Useful functions to calculate the offset between slices and show a hexdump of a slice
 pub trait Offset {
   /// Offset between the first byte of self and the first byte of the argument
+  /// the argument must be a part of self, otherwise this can fail with arithmetic
+  /// underflows as it compares byte offsets
   fn offset(&self, second: &Self) -> usize;
 }