Improve docs for ParseError::InvalidValue

Signed-off-by: Uli Schlachter <[email protected]>

src/errors.rs

@@ -62,14 +62,26 @@ pub enum ParseError {
 
     /// A value was outside of its valid range.
     ///
-    /// When parsing the value of an enumeration, not all possible integer values have a defined
-    /// meaning. This error occurs when an invalid value is encountered in this context.
+    /// There are two kinds of situations where this error can happen:
     ///
-    /// For example, `xproto` has an enumeration `Place` with possible values `OnTop` (0) and
-    /// `OnBottom` (1). Any value other than 0 or 1 generates an `InvalidValue` when parsing.
+    /// 1. The protocol was violated and a nonsensical value was found.
+    /// 2. The user of the API called the wrong parsing function.
+    ///
+    /// Examples for the first kind of error:
+    ///
+    /// - One of a set of values should be present (a `<switch>` in xcb-proto-speal), but none of
+    ///   the `<cases>` matched. This can e.g. happen when parsing
+    ///   [`x11rb::protocol::xinput::InputInfo`].
+    /// - Parsing a request with a length field that is too small for the request header to fit.
+    ///
+    /// Examples for the second kind of error:
+    ///
+    /// - Parsing an X11 error with `response_type != 0`.
+    /// - Parsing an X11 reply with `response_type != 1`.
+    /// - Parsing an X11 request with the wrong value for its `minor_opcode`.
     InvalidValue,
 
-    /// Some file descriptors were expected, but none were received.
+    /// Some file descriptors were expected, but not enough were received.
     MissingFileDescriptors,
 }