clean up misc from retro-review of #101

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Deprecated
+
+-   Deprecated `ResolveError` name.
+
 ### Fixed
 
 -   `EncodingError` and `ParseIndexError` now implement `Diagnostic`, which

src/delete.rs

@@ -7,7 +7,7 @@
 //! provided implementations (`"json"` & `"toml"`) operating as follows:
 //! - If the [`Pointer`] can be resolved, then the [`Value`](`Delete::Value`) is
 //!   deleted and returned as `Some(value)`.
-//! - If the [`Pointer`] fails to resolve for any reason, `Ok(None)` is
+//! - If the [`Pointer`] fails to resolve for any reason, `None` is
 //!   returned.
 //! - If the [`Pointer`] is root, `value` is replaced:
 //!     - `"json"` - `serde_json::Value::Null`

src/diagnostic.rs

@@ -21,8 +21,7 @@ pub trait Diagnostic: Sized {
     fn labels(&self, subject: &Self::Subject) -> Option<Box<dyn Iterator<Item = Label>>>;
 }
 
-/// A label for a span within a json pointer or malformed string.
-///
+/// A label for a span within a JSON Pointer or malformed string.
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub struct Label {
     text: String,
@@ -32,6 +31,9 @@ pub struct Label {
 
 impl Label {
     /// Creates a new instance of a [`Label`] from its parts
+    // NOTE: this is deliberately public, so that users can use
+    // the `Assign` and `Resolve` traits with custom types and errors,
+    // and then implement `Diagnostic` for those errors.
     pub fn new(text: String, offset: usize, len: usize) -> Self {
         Self { text, offset, len }
     }

src/pointer.rs

@@ -1149,20 +1149,6 @@ impl core::fmt::Display for PointerBuf {
     }
 }
 
-/// Indicates that a [`Pointer`] was unable to be parsed due to not containing
-/// a leading slash (`'/'`).
-#[derive(Debug, PartialEq, Eq, Clone, Copy)]
-pub struct NoLeadingSlash;
-
-impl fmt::Display for NoLeadingSlash {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(
-            f,
-            "json pointer must start with a slash ('/') and is not empty"
-        )
-    }
-}
-
 /// Indicates that a `Pointer` was malformed and unable to be parsed.
 #[derive(Debug, PartialEq)]
 pub enum ParseError {
@@ -1359,6 +1345,11 @@ const fn validate(value: &str) -> Result<&str, ParseError> {
     Ok(value)
 }
 
+/// Validates that a sequence of bytes is a valid RFC 6901 Pointer.
+///
+/// # Panics
+///
+/// Caller must ensure the sequence is non-empty, and that offset is in range.
 const fn validate_bytes(bytes: &[u8], offset: usize) -> Result<(), ParseError> {
     if bytes[0] != b'/' && offset == 0 {
         return Err(ParseError::NoLeadingSlash);

src/resolve.rs

@@ -76,8 +76,8 @@ pub trait ResolveMut {
     fn resolve_mut(&mut self, ptr: &Pointer) -> Result<&mut Self::Value, Self::Error>;
 }
 
-// TODO: should ResolveError be deprecated?
 /// Alias for [`Error`].
+#[deprecated(since = "0.7.2", note = "renamed to `Error`")]
 pub type ResolveError = Error;
 
 /// Indicates that the `Pointer` could not be resolved.