xso-proc: improve NestedMatcher documentation

skip-changelog

xso-proc/src/field/mod.rs

@@ -47,6 +47,20 @@ pub(crate) enum NestedMatcher {
         /// Expression which evaluates to `Result<T, FromEventsError>`,
         /// consuming `name: rxml::QName` and `attrs: rxml::AttrMap`.
         ///
+        /// If the `name` and `attrs` allow starting to parse the child
+        /// element as a value of this field, `Ok(_)` must be returned. If
+        /// the `name` and `attrs` are those of an element which *could*
+        /// be a value of this field, but they have invalid contents,
+        /// `Err(FromEventsError::Invalid(_))` must be returned. Depending
+        /// on the field kind, it may also be acceptable to return the
+        /// `Invalid` variant if the data is valid, but no further child
+        /// element can be accepted into the value.
+        ///
+        /// Otherwise, the `name` and `attrs` must be returned *unchanged* in
+        /// a `FromEventsError::Mismatch { .. }` variant. In that case, the
+        /// implementation in `Compound` will let the next field attempt to
+        /// parse the child element.
+        ///
         /// `T` must be the type specified in the
         /// [`FieldBuilderPart::Nested::builder`]  field.
         TokenStream,
@@ -61,6 +75,11 @@ pub(crate) enum NestedMatcher {
         /// Expression which evaluates to `T` (or `return`s an error),
         /// consuming `name: rxml::QName` and `attrs: rxml::AttrMap`.
         ///
+        /// Unlike the [`Selective`][`Self::Selective`] variant, this
+        /// expression must always evaluate to an instance of `T`. If that is
+        /// not possible, the expression must diverge, most commonly using
+        /// `return` with a `Err::<_, xso::error::Error>(_)`.
+        ///
         /// `T` must be the type specified in the
         /// [`FieldBuilderPart::Nested::builder`]  field.
         TokenStream,