Fix redundant/broken intradoc links and minor cleanup

.github/workflows/ci.yml

@@ -415,6 +415,8 @@ jobs:
 
       - name: Build Documentation
         uses: actions-rs/cargo@v1
+        env:
+          RUSTDOCFLAGS: -Dwarnings
         with:
           command: doc
           args: --all --no-deps --all-features

wayland-backend/src/client_api.rs

@@ -1,11 +1,16 @@
 use std::{
     any::Any,
     fmt,
-    os::unix::io::{BorrowedFd, OwnedFd},
-    os::unix::{io::RawFd, net::UnixStream},
+    os::unix::{
+        io::{BorrowedFd, OwnedFd, RawFd},
+        net::UnixStream,
+    },
     sync::Arc,
 };
 
+#[cfg(doc)]
+use std::io::ErrorKind::WouldBlock;
+
 use crate::protocol::{Interface, Message, ObjectInfo};
 
 use super::client_impl;
@@ -43,8 +48,8 @@ pub trait ObjectData: downcast_rs::DowncastSync {
 
     /// Helper for accessing user data
     ///
-    /// This function is used to back the `Proxy::data` function in `wayland_client`.  By default,
-    /// it returns `self` (via Downcast), but this may be overridden to allow downcasting user data
+    /// This function is used to back the `Proxy::data()` function in `wayland_client`.  By default,
+    /// it returns `self` (via [`Downcast`][downcast_rs::DowncastSync]), but this may be overridden to allow downcasting user data
     /// without needing to have access to the full type.
     fn data_as_any(&self) -> &dyn Any {
         self.as_any()
@@ -103,7 +108,7 @@ impl ObjectId {
     /// This object ID is always invalid, and should be used as placeholder in requests that create objects,
     /// or for request with an optional `Object` argument.
     ///
-    /// See [`Backend::send_request`](Backend::send_request) for details.
+    /// See [`Backend::send_request()`] for details.
     #[inline]
     pub fn null() -> ObjectId {
         client_impl::InnerBackend::null_id()
@@ -118,7 +123,7 @@ impl ObjectId {
     /// Return the protocol-level numerical ID of this object
     ///
     /// Protocol IDs are reused after object destruction, so this should not be used as a unique identifier,
-    /// instead use the `ObjectId` directly, it implements `Clone`, `PartialEq`, `Eq` and `Hash`.
+    /// instead use the [`ObjectId`] directly, it implements [`Clone`], [`PartialEq`], [`Eq`] and [`Hash`].
     #[inline]
     pub fn protocol_id(&self) -> u32 {
         self.id.protocol_id()
@@ -136,7 +141,7 @@ pub struct Backend {
 
 /// A weak handle to a [`Backend`]
 ///
-/// This handle behaves similarly to [`Weak`](std::sync::Weak), and can be used to keep access to
+/// This handle behaves similarly to [`Weak`][std::sync::Weak], and can be used to keep access to
 /// the backend without actually preventing it from being dropped.
 #[derive(Clone, Debug)]
 pub struct WeakBackend {
@@ -146,7 +151,7 @@ pub struct WeakBackend {
 impl WeakBackend {
     /// Try to upgrade this weak handle to a [`Backend`]
     ///
-    /// Returns `None` if the associated backend was already dropped.
+    /// Returns [`None`] if the associated backend was already dropped.
     pub fn upgrade(&self) -> Option<Backend> {
         self.inner.upgrade().map(|backend| Backend { backend })
     }
@@ -172,10 +177,10 @@ impl Backend {
     /// Flush all pending outgoing requests to the server
     ///
     /// Most errors on this method mean that the Wayland connection is no longer valid, the only
-    /// exception being an IO `WouldBlock` error. In that case it means that you should try flushing again
+    /// exception being an IO [`WouldBlock`] error. In that case it means that you should try flushing again
     /// later.
     ///
-    /// You can however expect this method returning `WouldBlock` to be very rare: it can only occur if
+    /// You can however expect this method returning [`WouldBlock`] to be very rare: it can only occur if
     /// either your client sent a lot of big messages at once, or the server is very laggy.
     pub fn flush(&self) -> Result<(), WaylandError> {
         self.backend.flush()
@@ -220,7 +225,7 @@ impl Backend {
     ///
     /// - the message opcode must be valid for the sender interface
     /// - the argument list must match the prototype for the message associated with this opcode
-    /// - if the method creates a new object, a [`ObjectId::null()`](ObjectId::null) must be given
+    /// - if the method creates a new object, a [`ObjectId::null()`] must be given
     ///   in the argument list at the appropriate place, and a `child_spec` (interface and version)
     ///   can be provided. If one is provided, it'll be checked against the protocol spec. If the
     ///   protocol specification does not define the interface of the created object (notable example
@@ -257,9 +262,9 @@ impl Backend {
     /// This is the first step for actually reading events from the Wayland socket. See
     /// [`ReadEventsGuard`] for how to use it.
     ///
-    /// This call will not block, but may return `None` if the inner queue of the backend needs to
+    /// This call will not block, but may return [`None`] if the inner queue of the backend needs to
     /// be dispatched. In which case you should invoke
-    /// [`dispatch_inner_queue()`](Backend::dispatch_inner_queue).
+    /// [`dispatch_inner_queue()`][Self::dispatch_inner_queue()].
     #[inline]
     #[must_use]
     pub fn prepare_read(&self) -> Option<ReadEventsGuard> {
@@ -271,12 +276,12 @@ impl Backend {
     ///
     /// This function actually only does something when using the system backend. It dispaches an inner
     /// queue that the backend uses to wrap `libwayland`. While this dispatching is generally done in
-    /// [`ReadEventsGuard::read()`](ReadEventsGuard::read), if multiple threads are interacting with the
+    /// [`ReadEventsGuard::read()`], if multiple threads are interacting with the
     /// Wayland socket it can happen that this queue was filled by another thread. In that case
-    /// [`prepare_read()`](Backend::prepare_read) will return `None`, and you should invoke
+    /// [`prepare_read()`][Self::prepare_read()] will return [`None`], and you should invoke
     /// this function instead of using the [`ReadEventsGuard`]
     ///
-    /// Returns the number of messages that were dispatched to their `ObjectData` callbacks.
+    /// Returns the number of messages that were dispatched to their [`ObjectData`] callbacks.
     #[inline]
     pub fn dispatch_inner_queue(&self) -> Result<usize, WaylandError> {
         self.backend.dispatch_inner_queue()
@@ -290,12 +295,12 @@ impl Backend {
 /// threads to not be notified of new events, and sleep much longer than appropriate.
 ///
 /// This guard is provided to ensure the proper synchronization is done. The guard is created using
-/// the [`Backend::prepare_read()`](Backend::prepare_read) method. And the event reading is
-/// triggered by consuming the guard using the [`read()`](ReadEventsGuard::read) method, synchronizing
+/// the [`Backend::prepare_read()`] method. And the event reading is
+/// triggered by consuming the guard using the [`ReadEventsGuard::read()`] method, synchronizing
 /// with other threads as necessary so that only one of the threads will actually perform the socket read.
 ///
 /// If you plan to poll the Wayland socket for readiness, the file descriptor can be retrieved via
-/// the [`connection_fd`](ReadEventsGuard::connection_fd) method. Note that for the synchronization to
+/// the [`ReadEventsGuard::connection_fd()`] method. Note that for the synchronization to
 /// correctly occur, you must *always* create the `ReadEventsGuard` *before* polling the socket.
 ///
 /// Dropping the guard is valid and will cancel the prepared read.
@@ -319,7 +324,7 @@ impl ReadEventsGuard {
     /// threads will then resume their execution.
     ///
     /// This returns the number of dispatched events, or `0` if an other thread handled the dispatching.
-    /// If no events are available to read from the socket, this returns a `WouldBlock` IO error.
+    /// If no events are available to read from the socket, this returns a [`WouldBlock`] IO error.
     #[inline]
     pub fn read(self) -> Result<usize, WaylandError> {
         self.guard.read()

wayland-backend/src/debug.rs

@@ -2,7 +2,7 @@
 
 use std::{
     fmt::Display,
-    os::unix::prelude::AsRawFd,
+    os::unix::io::AsRawFd,
     time::{SystemTime, UNIX_EPOCH},
 };
 
@@ -15,7 +15,7 @@ pub fn has_debug_client_env() -> bool {
 
 /// Print the dispatched message to stderr in a following format:
 ///
-/// [timestamp] <- [email protected]_name(args)
+/// `[timestamp] <- [email protected]_name(args)`
 #[cfg_attr(coverage, coverage(off))]
 pub fn print_dispatched_message<Id: Display, Fd: AsRawFd>(
     interface: &str,
@@ -34,7 +34,7 @@ pub fn print_dispatched_message<Id: Display, Fd: AsRawFd>(
 
 /// Print the send message to stderr in a following format:
 ///
-/// [timestamp] -> [email protected]_name(args)
+/// `[timestamp] -> [email protected]_name(args)`
 #[cfg_attr(coverage, coverage(off))]
 pub fn print_send_message<Id: Display, Fd: AsRawFd>(
     interface: &str,

wayland-backend/src/lib.rs

@@ -33,8 +33,8 @@
 //!
 //! ## raw-window-handle integration
 //!
-//! This crate can implement [`HasRawWindowHandle`](raw_window_handle::HasRawWindowHandle) for the client
-//! module [`Backend`](client::Backend) type if you activate the `raw-window-handle` feature.
+//! This crate can implement [`HasRawDisplayHandle`][raw_window_handle::HasRawDisplayHandle] for the client
+//! module [`Backend`][client::Backend] type if you activate the `raw-window-handle` feature.
 //!
 //! Note that the `client_system` feature must also be enabled for the implementation to be activated.
 
@@ -50,7 +50,7 @@
 /// Reexport of the `smallvec` crate, which is part of `wayland-backend`'s public API.
 pub extern crate smallvec;
 
-/// Helper macro for quickly making a [`Message`](crate::protocol::Message)
+/// Helper macro for quickly making a [`Message`][crate::protocol::Message]
 #[macro_export]
 macro_rules! message {
     ($sender_id: expr, $opcode: expr, [$($args: expr),* $(,)?] $(,)?) => {

wayland-backend/src/protocol.rs

@@ -1,6 +1,6 @@
 //! Types and utilities for manipulating the Wayland protocol
 
-use std::{ffi::CString, os::unix::prelude::AsRawFd};
+use std::{ffi::CString, os::unix::io::AsRawFd};
 
 pub use wayland_sys::common::{wl_argument, wl_interface, wl_message};
 

wayland-backend/src/rs/client_impl/mod.rs

@@ -2,9 +2,8 @@
 
 use std::{
     fmt,
-    os::unix::io::{BorrowedFd, OwnedFd},
     os::unix::{
-        io::{AsRawFd, RawFd},
+        io::{AsRawFd, BorrowedFd, OwnedFd, RawFd},
         net::UnixStream,
     },
     sync::{Arc, Condvar, Mutex, MutexGuard, Weak},

wayland-backend/src/rs/mod.rs

@@ -9,12 +9,12 @@ mod wire;
 
 /// Client-side rust implementation of a Wayland protocol backend
 ///
-/// The main entrypoint is the [`Backend::connect`](client::Backend::connect) method.
+/// The main entrypoint is the [`Backend::connect()`][client::Backend::connect()] method.
 #[path = "../client_api.rs"]
 pub mod client;
 
 /// Server-side rust implementation of a Wayland protocol backend
 ///
-/// The main entrypoint is the [`Backend::new`](server::Backend::new) method.
+/// The main entrypoint is the [`Backend::new()`][server::Backend::new()] method.
 #[path = "../server_api.rs"]
 pub mod server;

wayland-backend/src/rs/server_impl/client.rs

@@ -1,7 +1,9 @@
 use std::{
     ffi::CString,
-    os::unix::io::{AsFd, BorrowedFd, OwnedFd},
-    os::unix::{io::RawFd, net::UnixStream},
+    os::unix::{
+        io::{AsFd, BorrowedFd, OwnedFd, RawFd},
+        net::UnixStream,
+    },
     sync::Arc,
 };
 

wayland-backend/src/rs/server_impl/common_poll.rs

@@ -1,6 +1,5 @@
 use std::{
-    os::unix::io::AsRawFd,
-    os::unix::io::{BorrowedFd, OwnedFd},
+    os::unix::io::{AsRawFd, BorrowedFd, OwnedFd},
     sync::{Arc, Mutex},
 };
 

wayland-backend/src/rs/server_impl/handle.rs

@@ -1,7 +1,9 @@
 use std::{
     ffi::CString,
-    os::unix::io::OwnedFd,
-    os::unix::{io::RawFd, net::UnixStream},
+    os::unix::{
+        io::{OwnedFd, RawFd},
+        net::UnixStream,
+    },
     sync::{Arc, Mutex, Weak},
 };
 

wayland-backend/src/rs/socket.rs

@@ -333,8 +333,7 @@ mod tests {
     use crate::protocol::{AllowNull, Argument, ArgumentType, Message};
 
     use std::ffi::CString;
-    use std::os::unix::io::BorrowedFd;
-    use std::os::unix::prelude::IntoRawFd;
+    use std::os::unix::io::IntoRawFd;
 
     use smallvec::smallvec;
 

wayland-backend/src/rs/wire.rs

@@ -2,8 +2,7 @@
 
 use std::collections::VecDeque;
 use std::ffi::CStr;
-use std::os::unix::io::RawFd;
-use std::os::unix::io::{BorrowedFd, OwnedFd};
+use std::os::unix::io::{BorrowedFd, OwnedFd, RawFd};
 
 use crate::protocol::{Argument, ArgumentType, Message};
 

wayland-backend/src/server_api.rs

@@ -1,8 +1,10 @@
 use std::{
     ffi::CString,
     fmt,
-    os::unix::io::{BorrowedFd, OwnedFd},
-    os::unix::{io::RawFd, net::UnixStream},
+    os::unix::{
+        io::{BorrowedFd, OwnedFd, RawFd},
+        net::UnixStream,
+    },
     sync::Arc,
 };
 
@@ -230,15 +232,15 @@ impl fmt::Debug for GlobalId {
 ///
 /// This type hosts most of the protocol-related functionality of the backend, and is the
 /// main entry point for manipulating Wayland objects. It can be retrieved from the backend via
-/// [`Backend::handle()`](Backend::handle) and cloned, and is given to you as argument in many callbacks.
+/// [`Backend::handle()`] and cloned, and is given to you as argument in many callbacks.
 #[derive(Clone, Debug)]
 pub struct Handle {
     pub(crate) handle: server_impl::InnerHandle,
 }
 
 /// A weak reference to a [`Handle`]
 ///
-/// This handle behaves similarly to [`Weak`](std::sync::Weak), and can be used to keep access to
+/// This handle behaves similarly to [`Weak`][std::sync::Weak], and can be used to keep access to
 /// the handle without actually preventing it from being dropped.
 #[derive(Clone, Debug)]
 pub struct WeakHandle {
@@ -248,7 +250,7 @@ pub struct WeakHandle {
 impl WeakHandle {
     /// Try to upgrade this weak handle to a [`Handle`]
     ///
-    /// Returns `None` if the associated backend was already dropped.
+    /// Returns [`None`] if the associated backend was already dropped.
     #[inline]
     pub fn upgrade(&self) -> Option<Handle> {
         self.handle.upgrade().map(|handle| Handle { handle })
@@ -553,7 +555,7 @@ impl<D> Backend<D> {
     ///
     /// **Note:** This functionality is currently only available on the rust backend, invoking this method on
     /// the system backend will do the same as invoking
-    /// [`Backend::dispatch_all_clients()`](Backend::dispatch_all_clients).
+    /// [`Backend::dispatch_all_clients()`].
     #[inline]
     pub fn dispatch_single_client(
         &mut self,

wayland-backend/src/sys/client_impl/mod.rs

@@ -4,9 +4,8 @@ use std::{
     collections::HashSet,
     ffi::CStr,
     os::raw::{c_int, c_void},
-    os::unix::io::{BorrowedFd, OwnedFd},
     os::unix::{
-        io::{FromRawFd, IntoRawFd, RawFd},
+        io::{BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd},
         net::UnixStream,
     },
     sync::{