Improve error docs... and make some of the generated code a bit more readable

generator/src/generator/namespace.rs

@@ -543,7 +543,7 @@ impl<'ns, 'c> NamespaceGenerator<'ns, 'c> {
         outln!(out, "#[allow(unused_imports)]");
         outln!(
             out,
-            "use crate::x11_utils::{{Request, RequestHeader, Serialize, TryParse, TryParseFd}};"
+            "use crate::x11_utils::{{Request, RequestHeader, Serialize, TryParse, TryParseFd, TryIntoUSize}};"
         );
         outln!(
             out,
@@ -4056,7 +4056,7 @@ impl<'ns, 'c> NamespaceGenerator<'ns, 'c> {
                         outln!(
                             out,
                             "let ({}, remaining) = crate::x11_utils::parse_u8_list({}, \
-                             {}.try_into().or(Err(ParseError::ConversionFailed))?)?;",
+                             {}.try_to_usize()?)?;",
                             rust_field_name,
                             from,
                             self.expr_to_str(
@@ -4098,7 +4098,7 @@ impl<'ns, 'c> NamespaceGenerator<'ns, 'c> {
                     outln!(
                         out,
                         "let ({}, remaining) = crate::x11_utils::parse_list::<{}>(remaining, \
-                         {}.try_into().or(Err(ParseError::ConversionFailed))?)?;",
+                         {}.try_to_usize()?)?;",
                         rust_field_name,
                         rust_element_type,
                         self.expr_to_str(
@@ -4132,7 +4132,7 @@ impl<'ns, 'c> NamespaceGenerator<'ns, 'c> {
                         outln!(
                             out,
                             "let list_length = \
-                             usize::try_from({}).or(Err(ParseError::ConversionFailed))?;",
+                             {}.try_to_usize()?;",
                             self.expr_to_str(
                                 length_expr,
                                 to_rust_variable_name,
@@ -4198,7 +4198,7 @@ impl<'ns, 'c> NamespaceGenerator<'ns, 'c> {
 
                 outln!(
                     out,
-                    "let fds_len = usize::try_from({}).or(Err(ParseError::ConversionFailed))?;",
+                    "let fds_len = {}.try_to_usize()?;",
                     self.expr_to_str(
                         &fd_list_field.length_expr,
                         to_rust_variable_name,

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,
 }
 
@@ -102,7 +114,7 @@ pub enum ConnectError {
     ///
     /// One situation were this error is used when libxcb indicates an error that does not match
     /// any of the defined error conditions. Thus, libxcb is violating its own API (or new error
-    /// cases were defined, but are not yet handled by x11rb)
+    /// cases were defined, but are not yet handled by x11rb).
     UnknownError,
 
     /// Error while parsing some data, see `ParseError`.
@@ -115,10 +127,10 @@ pub enum ConnectError {
 
     /// Error during parsing of display string.
     ///
-    /// This is `XCB_CONN_CLOSSED_PARSE_ERR`.
+    /// This is `XCB_CONN_CLOSED_PARSE_ERR`.
     DisplayParsingError,
 
-    /// Server does not have a screen matcing the display.
+    /// Server does not have a screen matching the display.
     ///
     /// This is `XCB_CONN_CLOSED_INVALID_SCREEN`.
     InvalidScreen,
@@ -133,7 +145,7 @@ pub enum ConnectError {
 
     /// The server rejected the connection with a `SetupAuthenticate` message.
     SetupAuthenticate(SetupAuthenticate),
-    ///
+
     /// The server rejected the connection with a `SetupFailed` message.
     SetupFailed(SetupFailed),
 }
@@ -188,7 +200,7 @@ pub enum ConnectionError {
     ///
     /// One situation were this error is used when libxcb indicates an error that does not match
     /// any of the defined error conditions. Thus, libxcb is violating its own API (or new error
-    /// cases were defined, but are not yet handled by x11rb)
+    /// cases were defined, but are not yet handled by x11rb).
     UnknownError,
 
     /// An X11 extension was not supported by the server.
@@ -253,7 +265,7 @@ impl From<std::io::Error> for ConnectionError {
 pub enum ReplyError {
     /// Some error occurred on the X11 connection.
     ConnectionError(ConnectionError),
-    /// The X11 server sent an error in response to the request.
+    /// The X11 server sent an error in response to a request.
     X11Error(X11Error),
 }
 
@@ -299,7 +311,7 @@ pub enum ReplyOrIdError {
     IdsExhausted,
     /// Some error occurred on the X11 connection.
     ConnectionError(ConnectionError),
-    /// The X11 server sent an error in response to a XC-MISC request.
+    /// The X11 server sent an error in response to a request.
     X11Error(X11Error),
 }
 

src/protocol/bigreq.rs

@@ -17,7 +17,7 @@ use std::io::IoSlice;
 #[allow(unused_imports)]
 use crate::utils::{RawFdContainer, pretty_print_bitmask, pretty_print_enum};
 #[allow(unused_imports)]
-use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd};
+use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd, TryIntoUSize};
 use crate::connection::{BufWithFds, PiecewiseBuf, RequestConnection};
 #[allow(unused_imports)]
 use crate::cookie::{Cookie, CookieWithFds, VoidCookie};

src/protocol/composite.rs

@@ -17,7 +17,7 @@ use std::io::IoSlice;
 #[allow(unused_imports)]
 use crate::utils::{RawFdContainer, pretty_print_bitmask, pretty_print_enum};
 #[allow(unused_imports)]
-use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd};
+use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd, TryIntoUSize};
 use crate::connection::{BufWithFds, PiecewiseBuf, RequestConnection};
 #[allow(unused_imports)]
 use crate::cookie::{Cookie, CookieWithFds, VoidCookie};

src/protocol/damage.rs

@@ -17,7 +17,7 @@ use std::io::IoSlice;
 #[allow(unused_imports)]
 use crate::utils::{RawFdContainer, pretty_print_bitmask, pretty_print_enum};
 #[allow(unused_imports)]
-use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd};
+use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd, TryIntoUSize};
 use crate::connection::{BufWithFds, PiecewiseBuf, RequestConnection};
 #[allow(unused_imports)]
 use crate::cookie::{Cookie, CookieWithFds, VoidCookie};

src/protocol/dpms.rs

@@ -17,7 +17,7 @@ use std::io::IoSlice;
 #[allow(unused_imports)]
 use crate::utils::{RawFdContainer, pretty_print_bitmask, pretty_print_enum};
 #[allow(unused_imports)]
-use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd};
+use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd, TryIntoUSize};
 use crate::connection::{BufWithFds, PiecewiseBuf, RequestConnection};
 #[allow(unused_imports)]
 use crate::cookie::{Cookie, CookieWithFds, VoidCookie};

src/protocol/dri2.rs

@@ -17,7 +17,7 @@ use std::io::IoSlice;
 #[allow(unused_imports)]
 use crate::utils::{RawFdContainer, pretty_print_bitmask, pretty_print_enum};
 #[allow(unused_imports)]
-use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd};
+use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd, TryIntoUSize};
 use crate::connection::{BufWithFds, PiecewiseBuf, RequestConnection};
 #[allow(unused_imports)]
 use crate::cookie::{Cookie, CookieWithFds, VoidCookie};
@@ -509,11 +509,11 @@ impl TryParse for ConnectReply {
         let (driver_name_length, remaining) = u32::try_parse(remaining)?;
         let (device_name_length, remaining) = u32::try_parse(remaining)?;
         let remaining = remaining.get(16..).ok_or(ParseError::InsufficientData)?;
-        let (driver_name, remaining) = crate::x11_utils::parse_u8_list(remaining, driver_name_length.try_into().or(Err(ParseError::ConversionFailed))?)?;
+        let (driver_name, remaining) = crate::x11_utils::parse_u8_list(remaining, driver_name_length.try_to_usize()?)?;
         let driver_name = driver_name.to_vec();
-        let (alignment_pad, remaining) = crate::x11_utils::parse_u8_list(remaining, (driver_name_length.checked_add(3u32).ok_or(ParseError::InvalidExpression)? & (!3u32)).checked_sub(driver_name_length).ok_or(ParseError::InvalidExpression)?.try_into().or(Err(ParseError::ConversionFailed))?)?;
+        let (alignment_pad, remaining) = crate::x11_utils::parse_u8_list(remaining, (driver_name_length.checked_add(3u32).ok_or(ParseError::InvalidExpression)? & (!3u32)).checked_sub(driver_name_length).ok_or(ParseError::InvalidExpression)?.try_to_usize()?)?;
         let alignment_pad = alignment_pad.to_vec();
-        let (device_name, remaining) = crate::x11_utils::parse_u8_list(remaining, device_name_length.try_into().or(Err(ParseError::ConversionFailed))?)?;
+        let (device_name, remaining) = crate::x11_utils::parse_u8_list(remaining, device_name_length.try_to_usize()?)?;
         let device_name = device_name.to_vec();
         if response_type != 1 {
             return Err(ParseError::InvalidValue);
@@ -911,7 +911,7 @@ impl TryParse for GetBuffersReply {
         let (height, remaining) = u32::try_parse(remaining)?;
         let (count, remaining) = u32::try_parse(remaining)?;
         let remaining = remaining.get(12..).ok_or(ParseError::InsufficientData)?;
-        let (buffers, remaining) = crate::x11_utils::parse_list::<DRI2Buffer>(remaining, count.try_into().or(Err(ParseError::ConversionFailed))?)?;
+        let (buffers, remaining) = crate::x11_utils::parse_list::<DRI2Buffer>(remaining, count.try_to_usize()?)?;
         if response_type != 1 {
             return Err(ParseError::InvalidValue);
         }
@@ -1181,7 +1181,7 @@ impl TryParse for GetBuffersWithFormatReply {
         let (height, remaining) = u32::try_parse(remaining)?;
         let (count, remaining) = u32::try_parse(remaining)?;
         let remaining = remaining.get(12..).ok_or(ParseError::InsufficientData)?;
-        let (buffers, remaining) = crate::x11_utils::parse_list::<DRI2Buffer>(remaining, count.try_into().or(Err(ParseError::ConversionFailed))?)?;
+        let (buffers, remaining) = crate::x11_utils::parse_list::<DRI2Buffer>(remaining, count.try_to_usize()?)?;
         if response_type != 1 {
             return Err(ParseError::InvalidValue);
         }

src/protocol/dri3.rs

@@ -17,7 +17,7 @@ use std::io::IoSlice;
 #[allow(unused_imports)]
 use crate::utils::{RawFdContainer, pretty_print_bitmask, pretty_print_enum};
 #[allow(unused_imports)]
-use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd};
+use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd, TryIntoUSize};
 use crate::connection::{BufWithFds, PiecewiseBuf, RequestConnection};
 #[allow(unused_imports)]
 use crate::cookie::{Cookie, CookieWithFds, VoidCookie};
@@ -783,8 +783,8 @@ impl TryParse for GetSupportedModifiersReply {
         let (num_window_modifiers, remaining) = u32::try_parse(remaining)?;
         let (num_screen_modifiers, remaining) = u32::try_parse(remaining)?;
         let remaining = remaining.get(16..).ok_or(ParseError::InsufficientData)?;
-        let (window_modifiers, remaining) = crate::x11_utils::parse_list::<u64>(remaining, num_window_modifiers.try_into().or(Err(ParseError::ConversionFailed))?)?;
-        let (screen_modifiers, remaining) = crate::x11_utils::parse_list::<u64>(remaining, num_screen_modifiers.try_into().or(Err(ParseError::ConversionFailed))?)?;
+        let (window_modifiers, remaining) = crate::x11_utils::parse_list::<u64>(remaining, num_window_modifiers.try_to_usize()?)?;
+        let (screen_modifiers, remaining) = crate::x11_utils::parse_list::<u64>(remaining, num_screen_modifiers.try_to_usize()?)?;
         if response_type != 1 {
             return Err(ParseError::InvalidValue);
         }
@@ -980,7 +980,7 @@ impl PixmapFromBuffersRequest {
         let (bpp, remaining) = u8::try_parse(remaining)?;
         let remaining = remaining.get(2..).ok_or(ParseError::InsufficientData)?;
         let (modifier, remaining) = u64::try_parse(remaining)?;
-        let fds_len = usize::try_from(num_buffers).or(Err(ParseError::ConversionFailed))?;
+        let fds_len = num_buffers.try_to_usize()?;
         if fds.len() < fds_len { return Err(ParseError::MissingFileDescriptors) }
         let mut buffers = fds.split_off(fds_len);
         std::mem::swap(fds, &mut buffers);
@@ -1125,9 +1125,9 @@ impl TryParseFd for BuffersFromPixmapReply {
         let (depth, remaining) = u8::try_parse(remaining)?;
         let (bpp, remaining) = u8::try_parse(remaining)?;
         let remaining = remaining.get(6..).ok_or(ParseError::InsufficientData)?;
-        let (strides, remaining) = crate::x11_utils::parse_list::<u32>(remaining, nfd.try_into().or(Err(ParseError::ConversionFailed))?)?;
-        let (offsets, remaining) = crate::x11_utils::parse_list::<u32>(remaining, nfd.try_into().or(Err(ParseError::ConversionFailed))?)?;
-        let fds_len = usize::try_from(nfd).or(Err(ParseError::ConversionFailed))?;
+        let (strides, remaining) = crate::x11_utils::parse_list::<u32>(remaining, nfd.try_to_usize()?)?;
+        let (offsets, remaining) = crate::x11_utils::parse_list::<u32>(remaining, nfd.try_to_usize()?)?;
+        let fds_len = nfd.try_to_usize()?;
         if fds.len() < fds_len { return Err(ParseError::MissingFileDescriptors) }
         let mut buffers = fds.split_off(fds_len);
         std::mem::swap(fds, &mut buffers);

src/protocol/ge.rs

@@ -17,7 +17,7 @@ use std::io::IoSlice;
 #[allow(unused_imports)]
 use crate::utils::{RawFdContainer, pretty_print_bitmask, pretty_print_enum};
 #[allow(unused_imports)]
-use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd};
+use crate::x11_utils::{Request, RequestHeader, Serialize, TryParse, TryParseFd, TryIntoUSize};
 use crate::connection::{BufWithFds, PiecewiseBuf, RequestConnection};
 #[allow(unused_imports)]
 use crate::cookie::{Cookie, CookieWithFds, VoidCookie};