Minor documentation changes

src/reader/mod.rs

@@ -109,15 +109,16 @@ pub mod json_path {
     /// ```
     /// # #![allow(deprecated)]
     /// # use struson::reader::json_path::*;
+    /// # use struson::reader::json_path::JsonPathPiece::*;
     /// let json_path = parse_json_path("outer[1].inner[2][3]")?;
     /// assert_eq!(
     ///     json_path,
     ///     vec![
-    ///         JsonPathPiece::ObjectMember("outer".to_owned()),
-    ///         JsonPathPiece::ArrayItem(1),
-    ///         JsonPathPiece::ObjectMember("inner".to_owned()),
-    ///         JsonPathPiece::ArrayItem(2),
-    ///         JsonPathPiece::ArrayItem(3),
+    ///         ObjectMember("outer".to_owned()),
+    ///         ArrayItem(1),
+    ///         ObjectMember("inner".to_owned()),
+    ///         ArrayItem(2),
+    ///         ArrayItem(3),
     ///     ]
     /// );
     /// # Ok::<(), Box<dyn std::error::Error>>(())
@@ -257,13 +258,14 @@ pub mod json_path {
     /// # Examples
     /// ```
     /// # use struson::reader::json_path::*;
+    /// # use struson::reader::json_path::JsonPathPiece::*;
     /// let json_path = json_path!["outer", 3, "inner"];
     /// assert_eq!(
     ///     json_path,
     ///     [
-    ///         JsonPathPiece::ObjectMember("outer".to_owned()),
-    ///         JsonPathPiece::ArrayItem(3),
-    ///         JsonPathPiece::ObjectMember("inner".to_owned()),
+    ///         ObjectMember("outer".to_owned()),
+    ///         ArrayItem(3),
+    ///         ObjectMember("inner".to_owned()),
     ///     ]
     /// );
     /// ```
@@ -1693,7 +1695,7 @@ pub trait JsonReader {
 
     /// Opposite of [`seek_to`](Self::seek_to)
     ///
-    /// This is the opposite of the `seek_to` method, it goes through the path in reverse
+    /// This is the opposite of the `seek_to` method; it goes through the path in reverse
     /// order skipping remaining JSON array items and object members and closing arrays
     /// and objects. Therefore once this method returns the reader is at the same nesting
     /// level it was before `seek_to` had been called and allows continuing reading

src/reader/simple.rs

@@ -236,13 +236,13 @@ pub mod multi_json_path {
     ///
     /// | Argument | Path piece |
     /// | - | - |
-    /// | number of type `u32` | [`MultiJsonPathPiece::ArrayItem`] |
-    /// | string | [`MultiJsonPathPiece::ObjectMember`] |
-    /// | '`?`_string_' | [`MultiJsonPathPiece::OptionalObjectMember`] |
-    /// | '`[*]`' | [`MultiJsonPathPiece::AllArrayItems { allow_empty: true }`](MultiJsonPathPiece::AllArrayItems) |
-    /// | '`[+]`' | [`MultiJsonPathPiece::AllArrayItems { allow_empty: false }`](MultiJsonPathPiece::AllArrayItems) |
-    /// | '`{*}`' | [`MultiJsonPathPiece::AllObjectMembers { allow_empty: true }`](MultiJsonPathPiece::AllObjectMembers) |
-    /// | '`{+}`' | [`MultiJsonPathPiece::AllObjectMembers { allow_empty: false }`](MultiJsonPathPiece::AllObjectMembers) |
+    /// | number of type `u32` | [`ArrayItem`](MultiJsonPathPiece::ArrayItem) |
+    /// | string | [`ObjectMember`](MultiJsonPathPiece::ObjectMember) |
+    /// | '`?`string' | [`OptionalObjectMember`](MultiJsonPathPiece::OptionalObjectMember) |
+    /// | '`[*]`' | [`AllArrayItems { allow_empty: true }`](MultiJsonPathPiece::AllArrayItems) |
+    /// | '`[+]`' | [`AllArrayItems { allow_empty: false }`](MultiJsonPathPiece::AllArrayItems) |
+    /// | '`{*}`' | [`AllObjectMembers { allow_empty: true }`](MultiJsonPathPiece::AllObjectMembers) |
+    /// | '`{+}`' | [`AllObjectMembers { allow_empty: false }`](MultiJsonPathPiece::AllObjectMembers) |
     ///
     /// Providing no arguments creates an empty path without any path pieces.
     ///
@@ -266,24 +266,25 @@ pub mod multi_json_path {
     /// }
     /// ```
     ///
-    /// Then the following multi JSON path could be used to match all awards any book has
+    /// Then the following multi JSON path can be used to match all awards any book has
     /// received:
     /// ```
     /// # use struson::reader::simple::multi_json_path::*;
+    /// # use struson::reader::simple::multi_json_path::MultiJsonPathPiece::*;
     /// let json_path = multi_json_path![
     ///     "books",
     ///     [*], // match all books
     ///     ?"awards", // match the optional "awards" member
-    ///     [+], // match all awards
+    ///     [+], // match all awards (requiring non-empty array)
     /// ];
     ///
     /// assert_eq!(
     ///     json_path,
     ///     [
-    ///         MultiJsonPathPiece::ObjectMember("books".to_owned()),
-    ///         MultiJsonPathPiece::AllArrayItems { allow_empty: true },
-    ///         MultiJsonPathPiece::OptionalObjectMember("awards".to_owned()),
-    ///         MultiJsonPathPiece::AllArrayItems { allow_empty: false },
+    ///         ObjectMember("books".to_owned()),
+    ///         AllArrayItems { allow_empty: true },
+    ///         OptionalObjectMember("awards".to_owned()),
+    ///         AllArrayItems { allow_empty: false },
     ///     ]
     /// );
     /// ```
@@ -761,20 +762,19 @@ pub trait ValueReader<J: JsonReader> {
     ///
     /// Depending on what pieces the path consists of, it can match any number of values, including
     /// none. The `at_least_one_match` argument determines the behavior of this method in case the
-    /// path can potentially match no values. If `true` an error is returned, if `false` no error is
-    /// returned but `f` is also not called. `at_least_one_match` can for example be useful when a
-    /// [JSON object member is optional](MultiJsonPathPiece::OptionalObjectMember) but for multiple
-    /// of such objects at least one is expected to have the member.\
-    /// `at_least_one_match = false` does not override the behavior for path pieces which themself
-    /// require at least one match, such as [`MultiJsonPathPiece::AllArrayItems { allow_empty: false }`](MultiJsonPathPiece::AllArrayItems).
-    ///
-    /// For [`MultiJsonPathPiece::ObjectMember`] and [`MultiJsonPathPiece::OptionalObjectMember`]
-    /// if multiple members in a JSON object have the same name (for example `{"a": 1, "a": 2}`)
+    /// path matches no values. If `true` an error is returned; this can for example be useful when
+    /// a JSON object member is [optional](MultiJsonPathPiece::OptionalObjectMember) but for multiple
+    /// of such objects at least one is expected to have the member. If `false` no error is returned
+    /// but `f` is also not called. This does not override the behavior for path pieces which themself
+    /// require at least one match, such as [`AllArrayItems { allow_empty: false }`](MultiJsonPathPiece::AllArrayItems).
+    ///
+    /// For [`ObjectMember`](MultiJsonPathPiece::ObjectMember) and [`OptionalObjectMember`](MultiJsonPathPiece::OptionalObjectMember)
+    /// pieces if multiple members in a JSON object have the same name (for example `{"a": 1, "a": 2}`)
     /// this method will only seek to the first occurrence in that object ignoring the others.
     ///
     /// Once this method returns, the reader is at the original nesting level again and can continue
-    /// consuming values there, if any. Calling this method therefore acts as if it only consumed
-    /// one value (and its nested values) at the current level.
+    /// consuming values there. Calling this method therefore acts as if it only consumed one value
+    /// (and its nested values) at the that level.
     ///
     /// If the structure of the JSON data does not match the path, for example the JSON data contains
     /// an array but the path expects an object, an error is returned.
@@ -1255,8 +1255,8 @@ impl<J: JsonReader> SimpleJsonReader<J> {
     ///
     /// The seeking behavior of this method is equivalent to [`read_seeked`](Self::read_seeked), but
     /// `seek_to` allows consuming the value afterwards without having to use a closure or separate
-    /// function (as required by `read_seeked`), however it is only available at the top-level
-    /// and not at nested levels in the JSON document.
+    /// function (as required by `read_seeked`), however it is only available for `SimpleJsonReader`
+    /// and not generally for the `ValueReader` trait.
     ///
     /// # Examples
     /// ```

src/reader/stream_reader.rs

@@ -2210,7 +2210,7 @@ impl<R: Read> JsonReader for JsonStreamReader<R> {
 
     fn skip_to_top_level(&mut self) -> Result<(), ReaderError> {
         if self.is_string_value_reader_active {
-            panic!("Incorrect reader usage: Cannot skip to top level when string value reader is active");
+            panic!("Incorrect reader usage: Cannot skip to top-level when string value reader is active");
         }
 
         // Handle expected member value separately because has_next() calls below are not allowed when

src/writer/stream_writer.rs

@@ -94,7 +94,7 @@ impl Default for WriterSettings {
     ///
     /// - pretty print: disabled (= compact JSON will be written)
     /// - escape all control chars: false (= only control characters `0x00` to `0x1F` are escaped)
-    /// - multiple top level values: disallowed
+    /// - multiple top-level values: disallowed
     fn default() -> Self {
         WriterSettings {
             pretty_print: false,

tests/custom_json_reader.rs

@@ -37,7 +37,7 @@ mod custom_reader {
     pub struct JsonValueReader<'a> {
         /// Contains the next value to consume
         ///
-        /// Either the top level value, or the next value in arrays or for object members.
+        /// Either the top-level value, or the next value in arrays or for object members.
         next_value: Option<&'a Value>,
         stack: Vec<StackValue<'a>>,
         /// Whether the reader is currently in a JSON object and expects a name (or end of the JSON object)