From a8b218ea8f1917f7035ab5f7c6d4963d766f5741 Mon Sep 17 00:00:00 2001 From: Marijn Suijten Date: Wed, 24 Apr 2024 00:30:12 +0200 Subject: [PATCH] intradoc-link redundancy fixes --- wayland-backend/src/client_api.rs | 35 +++++++++++++++------------- wayland-backend/src/lib.rs | 6 ++--- wayland-backend/src/rs/mod.rs | 4 ++-- wayland-backend/src/server_api.rs | 6 ++--- wayland-backend/src/sys/mod.rs | 18 +++++++-------- wayland-client/src/conn.rs | 22 +++++++++--------- wayland-client/src/event_queue.rs | 38 +++++++++++++++---------------- wayland-client/src/globals.rs | 6 ++--- wayland-client/src/lib.rs | 17 +++++++------- wayland-cursor/src/lib.rs | 2 +- wayland-egl/src/lib.rs | 6 ++--- wayland-server/src/client.rs | 4 ++-- wayland-server/src/dispatch.rs | 18 +++++++-------- wayland-server/src/display.rs | 10 ++++---- wayland-server/src/global.rs | 4 ++-- wayland-server/src/lib.rs | 12 +++++----- wayland-server/src/socket.rs | 10 ++++---- 17 files changed, 109 insertions(+), 109 deletions(-) diff --git a/wayland-backend/src/client_api.rs b/wayland-backend/src/client_api.rs index a8633657e5c..a9234b46310 100644 --- a/wayland-backend/src/client_api.rs +++ b/wayland-backend/src/client_api.rs @@ -6,6 +6,9 @@ use std::{ sync::Arc, }; +#[cfg(doc)] +use std::io::ErrorKind::WouldBlock; + use crate::protocol::{Interface, Message, ObjectInfo}; use super::client_impl; @@ -43,8 +46,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 +106,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 +121,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 +139,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 { @@ -172,10 +175,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 +223,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 @@ -259,7 +262,7 @@ impl Backend { /// /// 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 { @@ -271,12 +274,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 { self.backend.dispatch_inner_queue() @@ -290,12 +293,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 +322,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 { self.guard.read() diff --git a/wayland-backend/src/lib.rs b/wayland-backend/src/lib.rs index 27fed3040e2..a324d482b90 100644 --- a/wayland-backend/src/lib.rs +++ b/wayland-backend/src/lib.rs @@ -33,8 +33,8 @@ //! //! ## raw-window-handle integration //! -//! 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. +//! 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),* $(,)?] $(,)?) => { diff --git a/wayland-backend/src/rs/mod.rs b/wayland-backend/src/rs/mod.rs index dfc727be593..da6d0b68953 100644 --- a/wayland-backend/src/rs/mod.rs +++ b/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; diff --git a/wayland-backend/src/server_api.rs b/wayland-backend/src/server_api.rs index 6e3565db1c0..c52348ae5f2 100644 --- a/wayland-backend/src/server_api.rs +++ b/wayland-backend/src/server_api.rs @@ -230,7 +230,7 @@ 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, @@ -238,7 +238,7 @@ pub struct Handle { /// 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 { @@ -551,7 +551,7 @@ impl Backend { /// /// **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, diff --git a/wayland-backend/src/sys/mod.rs b/wayland-backend/src/sys/mod.rs index fc150ecd994..eacd7051556 100644 --- a/wayland-backend/src/sys/mod.rs +++ b/wayland-backend/src/sys/mod.rs @@ -26,8 +26,8 @@ unsafe fn free_arrays(signature: &[ArgumentType], arglist: &[wl_argument]) { /// Client-side implementation of a Wayland protocol backend using `libwayland` /// /// Entrypoints are: -/// - [`Backend::connect`](client::Backend::connect) method if you're creating the Wayland connection -/// - [`Backend::from_foreign_display`](client::Backend::from_foreign_display) if you're interacting with an +/// - [`Backend::connect()`][client::Backend::connect()] method if you're creating the Wayland connection +/// - [`Backend::from_foreign_display()`][client::Backend::from_foreign_display()] if you're interacting with an /// already existing Wayland connection through FFI. #[cfg(any(test, feature = "client_system"))] #[path = "../client_api.rs"] @@ -41,7 +41,7 @@ impl client::ObjectId { /// /// # Errors /// - /// This function returns an [`InvalidId`](client::InvalidId) error if the interface of the proxy does + /// This function returns an [`InvalidId`][client::InvalidId] error if the interface of the proxy does /// not match the provided interface. /// /// # Safety @@ -68,15 +68,15 @@ impl client::Backend { /// This is useful if you are writing a library that is expected to plug itself into an existing /// Wayland connection. /// - /// This will initialize the [`Backend`](client::Backend) in "guest" mode, meaning it will not close the - /// connection on drop. After the [`Backend`](client::Backend) is dropped, if the server sends an event + /// This will initialize the [`Backend`][Self] in "guest" mode, meaning it will not close the + /// connection on drop. After the [`Backend`][Self] is dropped, if the server sends an event /// to an object that was created from it, that event will be silently discarded. This may lead to /// protocol errors if the server expects an answer to that event, as such you should make sure to - /// cleanup your Wayland state before dropping the [`Backend`](client::Backend). + /// cleanup your Wayland state before dropping the [`Backend`][Self]. /// /// # Safety /// - /// You need to ensure the `*mut wl_display` remains live as long as the [`Backend`](client::Backend) + /// You need to ensure the `*mut wl_display` remains live as long as the [`Backend`][Self] /// (or its clones) exist. pub unsafe fn from_foreign_display(display: *mut wayland_sys::client::wl_display) -> Self { Self { backend: unsafe { client_impl::InnerBackend::from_foreign_display(display) } } @@ -107,7 +107,7 @@ unsafe impl raw_window_handle::HasRawDisplayHandle for client::Backend { /// Server-side implementation of a Wayland protocol backend using `libwayland` /// -/// The main entrypoint is the [`Backend::new`](server::Backend::new) method. +/// The main entrypoint is the [`Backend::new()`][server::Backend::new()] method. #[cfg(any(test, feature = "server_system"))] #[path = "../server_api.rs"] pub mod server; @@ -118,7 +118,7 @@ impl server::ObjectId { /// /// # Errors /// - /// This function returns an [`InvalidId`](server::InvalidId) error if the interface of the + /// This function returns an [`InvalidId`][server::InvalidId] error if the interface of the /// resource does not match the provided interface. /// /// # Safety diff --git a/wayland-client/src/conn.rs b/wayland-client/src/conn.rs index 5900ac54c29..81b1664c0e1 100644 --- a/wayland-client/src/conn.rs +++ b/wayland-client/src/conn.rs @@ -23,17 +23,17 @@ use crate::{protocol::wl_display::WlDisplay, EventQueue, Proxy}; /// with the protocol are actually done using other types. The two main uses a simple app has for the /// [`Connection`] are: /// -/// - Obtaining the initial [`WlDisplay`] through the [`display()`](Connection::display) method. -/// - Creating new [`EventQueue`]s with the [`new_event_queue()`](Connection::new_event_queue) method. +/// - Obtaining the initial [`WlDisplay`] through the [`display()`][Self::display()] method. +/// - Creating new [`EventQueue`]s with the [`new_event_queue()`][Self::new_event_queue()] method. /// -/// It can be created through the [`connect_to_env()`](Connection::connect_to_env) method to follow the +/// It can be created through the [`connect_to_env()`][Self::connect_to_env()] method to follow the /// configuration from the environment (which is what you'll do most of the time), or using the -/// [`from_socket()`](Connection::from_socket) method if you retrieved your connected Wayland socket through +/// [`from_socket()`][Self::from_socket()] method if you retrieved your connected Wayland socket through /// other means. /// /// In case you need to plug yourself into an external Wayland connection that you don't control, you'll /// likely get access to it as a [`Backend`], in which case you can create a [`Connection`] from it using -/// the [`from_backend`](Connection::from_backend) method. +/// the [`from_backend()`][Self::from_backend()] method. #[derive(Debug, Clone, PartialEq, Eq)] pub struct Connection { pub(crate) backend: Backend, @@ -129,10 +129,10 @@ impl Connection { /// /// This is needed if you plan to wait on readiness of the Wayland socket using an event loop. See /// [`ReadEventsGuard`] for details. Once the events are received, you'll then need to dispatch them from - /// their event queues using [`EventQueue::dispatch_pending()`](EventQueue::dispatch_pending). + /// their event queues using [`EventQueue::dispatch_pending()`]. /// /// If you don't need to manage multiple event sources, see - /// [`blocking_dispatch()`](EventQueue::blocking_dispatch) for a simpler mechanism. + /// [`EventQueue::blocking_dispatch()`] for a simpler mechanism. #[must_use] pub fn prepare_read(&self) -> Option { self.backend.prepare_read() @@ -188,8 +188,8 @@ impl Connection { /// Send a request associated with the provided object /// /// This is a low-level interface used by the code generated by `wayland-scanner`, you will likely - /// instead use the methods of the types representing each interface, or the [`Proxy::send_request`] and - /// [`Proxy::send_constructor`] + /// instead use the methods of the types representing each interface, or the [`Proxy::send_request()`] and + /// [`Proxy::send_constructor()`]. pub fn send_request( &self, proxy: &I, @@ -209,7 +209,7 @@ impl Connection { /// Get the object data for a given object ID /// /// This is a low-level interface used by the code generated by `wayland-scanner`, a higher-level - /// interface for manipulating the user-data assocated to [`Dispatch`](crate::Dispatch) implementations + /// interface for manipulating the user-data assocated to [`Dispatch`][crate::Dispatch] implementations /// is given as [`Proxy::data()`]. Also see [`Proxy::object_data()`]. pub fn get_object_data(&self, id: ObjectId) -> Result, InvalidId> { self.backend.get_data(id) @@ -272,7 +272,7 @@ impl fmt::Display for ConnectError { } impl AsFd for Connection { - /// Provides fd from [`Backend::poll_fd`] for polling. + /// Provides fd from [`Backend::poll_fd()`] for polling. fn as_fd(&self) -> BorrowedFd<'_> { self.backend.poll_fd() } diff --git a/wayland-client/src/event_queue.rs b/wayland-client/src/event_queue.rs index 03c119290ee..038aca4bcd3 100644 --- a/wayland-client/src/event_queue.rs +++ b/wayland-client/src/event_queue.rs @@ -30,14 +30,14 @@ use crate::{conn::SyncData, Connection, DispatchError, Proxy}; /// /// In the rare case of an interface with *events* creating new objects (in the core protocol, the only /// instance of this is the `wl_data_device.data_offer` event), you'll need to implement the -/// [`Dispatch::event_created_child()`] method. See the [`event_created_child!`](macro.event_created_child.html) macro +/// [`Dispatch::event_created_child()`] method. See the [`crate::event_created_child!()`] macro /// for a simple way to do this. /// /// ## Modularity /// /// To provide generic handlers for downstream usage, it is possible to make an implementation of the trait /// that is generic over the last type argument, as illustrated below. Users will then be able to -/// automatically delegate their implementation to yours using the [`delegate_dispatch!`] macro. +/// automatically delegate their implementation to yours using the [`crate::delegate_dispatch!()`] macro. /// /// As a result, when your implementation is instantiated, the last type parameter `State` will be the state /// struct of the app using your generic implementation. You can put additional trait constraints on it to @@ -88,8 +88,6 @@ use crate::{conn::SyncData, Connection, DispatchError, Proxy}; /// implementation of [`Dispatch`] cannot be used directly as the dispatching state, as rustc /// currently fails to understand that it also provides `Dispatch` (assuming all other /// trait bounds are respected as well). -/// -/// [`delegate_dispatch!`]: crate::delegate_dispatch pub trait Dispatch where Self: Sized, @@ -119,7 +117,7 @@ where /// Method used to initialize the user-data of objects created by events /// /// If the interface does not have any such event, you can ignore it. If not, the - /// [`event_created_child!`](macro.event_created_child.html) macro is provided for overriding it. + /// [`crate::event_created_child!()`] macro is provided for overriding it. #[cfg_attr(coverage, coverage(off))] fn event_created_child(opcode: u16, _qhandle: &QueueHandle) -> Arc { panic!( @@ -205,12 +203,12 @@ impl std::fmt::Debug for QueueEvent { /// This is an abstraction for handling event dispatching, that allows you to ensure /// access to some common state `&mut State` to your event handlers. /// -/// Event queues are created through [`Connection::new_event_queue()`](crate::Connection::new_event_queue). +/// Event queues are created through [`Connection::new_event_queue()`]. /// /// Upon creation, a wayland object is assigned to an event queue by passing the associated [`QueueHandle`] /// as argument to the method creating it. All events received by that object will be processed by that event -/// queue, when [`dispatch_pending()`](EventQueue::dispatch_pending) or -/// [`blocking_dispatch()`](EventQueue::blocking_dispatch) is invoked. +/// queue, when [`dispatch_pending()`][Self::dispatch_pending()] or +/// [`blocking_dispatch()`][Self::blocking_dispatch()] is invoked. /// /// ## Usage /// @@ -239,10 +237,10 @@ impl std::fmt::Debug for QueueEvent { /// } /// ``` /// -/// The [`blocking_dispatch()`](EventQueue::blocking_dispatch) will wait (by putting the thread to sleep) +/// The [`blocking_dispatch()`][Self::blocking_dispatch()] call will wait (by putting the thread to sleep) /// until there are some events from the server that can be processed, and all your actual app logic can be /// done in the callbacks of the [`Dispatch`] implementations, and in the main `loop` after the -/// `blocking_dispatch()` call. +/// [`blocking_dispatch()`][Self::blocking_dispatch()] call. /// /// ### Multi-thread multi-queue app /// @@ -257,14 +255,14 @@ impl std::fmt::Debug for QueueEvent { /// If your code is some library code that will act on a Wayland connection shared by the main program, it is /// likely you should not trigger socket reads yourself and instead let the main app take care of it. In this /// case, to ensure your [`EventQueue`] still makes progress, you should regularly invoke -/// [`EventQueue::dispatch_pending()`](EventQueue::dispatch_pending) which will process the events that were +/// [`EventQueue::dispatch_pending()`] which will process the events that were /// enqueued in the inner buffer of your [`EventQueue`] by the main app reading the socket. /// /// ### Integrating the event queue with other sources of events /// /// If your program needs to monitor other sources of events alongside the Wayland socket using a monitoring /// system like `epoll`, you can integrate the Wayland socket into this system. This is done with the help -/// of the [`EventQueue::prepare_read()`](EventQueue::prepare_read) method. You event loop will be a bit more +/// of the [`EventQueue::prepare_read()`] method. You event loop will be a bit more /// explicit: /// /// ```rust,no_run @@ -375,9 +373,9 @@ impl EventQueue { /// Dispatch pending events /// /// Events are accumulated in the event queue internal buffer when the Wayland socket is read using - /// the read APIs on [`Connection`](crate::Connection), or when reading is done from an other thread. + /// the read APIs on [`Connection`], or when reading is done from an other thread. /// This method will dispatch all such pending events by sequentially invoking their associated handlers: - /// the [`Dispatch`](crate::Dispatch) implementations on the provided `&mut D`. + /// the [`Dispatch`][crate::Dispatch] implementations on the provided `&mut D`. /// /// Note: this may block if another thread has frozen the queue. pub fn dispatch_pending(&mut self, data: &mut State) -> Result { @@ -386,7 +384,7 @@ impl EventQueue { /// Block waiting for events and dispatch them /// - /// This method is similar to [`dispatch_pending`](EventQueue::dispatch_pending), but if there are no + /// This method is similar to [`dispatch_pending()`][Self::dispatch_pending], but if there are no /// pending events it will also flush the connection and block waiting for the Wayland server to send an /// event. /// @@ -439,13 +437,13 @@ impl EventQueue { /// This is needed if you plan to wait on readiness of the Wayland socket using an event /// loop. See the [`EventQueue`] and [`ReadEventsGuard`] docs for details. Once the events are received, /// you'll then need to dispatch them from the event queue using - /// [`EventQueue::dispatch_pending()`](EventQueue::dispatch_pending). + /// [`EventQueue::dispatch_pending()`]. /// - /// If this method returns `None`, you should invoke ['dispatch_pending()`](EventQueue::dispatch_pending) + /// If this method returns [`None`], you should invoke ['dispatch_pending()`][Self::dispatch_pending] /// before trying to invoke it again. /// /// If you don't need to manage multiple event sources, see - /// [`blocking_dispatch()`](EventQueue::blocking_dispatch) for a simpler mechanism. + /// [`blocking_dispatch()`][Self::blocking_dispatch()] for a simpler mechanism. /// /// This method is identical to [`Connection::prepare_read()`]. #[must_use] @@ -496,7 +494,7 @@ impl EventQueue { /// Attempt to dispatch events from this queue, registering the current task for wakeup if no /// events are pending. /// - /// This method is similar to [`dispatch_pending`](EventQueue::dispatch_pending); it will not + /// This method is similar to [`dispatch_pending()`][Self::dispatch_pending]; it will not /// perform reads on the Wayland socket. Reads on the socket by other tasks or threads will /// cause the current task to wake up if events are pending on this queue. /// @@ -725,7 +723,7 @@ impl ObjectData for TemporaryData { /// /// # Usage /// -/// For example, say you want to delegate events for [`WlRegistry`](crate::protocol::wl_registry::WlRegistry) +/// For example, say you want to delegate events for [`WlRegistry`][crate::protocol::wl_registry::WlRegistry] /// to the struct `DelegateToMe` for the [`Dispatch`] documentatione example. /// /// ``` diff --git a/wayland-client/src/globals.rs b/wayland-client/src/globals.rs index dc897a3edfc..d422b6962b6 100644 --- a/wayland-client/src/globals.rs +++ b/wayland-client/src/globals.rs @@ -74,7 +74,7 @@ use crate::{ /// Initialize a new event queue with its associated registry and retrieve the initial list of globals /// -/// See [the module level documentation](self) for more. +/// See [the module level documentation][self] for more. pub fn registry_queue_init( conn: &Connection, ) -> Result<(GlobalList, EventQueue), GlobalError> @@ -97,7 +97,7 @@ where /// A helper for global initialization. /// -/// See [the module level documentation](self) for more. +/// See [the module level documentation][self] for more. #[derive(Debug)] pub struct GlobalList { registry: wl_registry::WlRegistry, @@ -178,7 +178,7 @@ impl GlobalList { Ok(self.registry.bind(name, version, qh, udata)) } - /// Returns the [`WlRegistry`](wl_registry) protocol object. + /// Returns the [`WlRegistry`][wl_registry] protocol object. /// /// This may be used if more direct control when creating globals is needed. pub fn registry(&self) -> &wl_registry::WlRegistry { diff --git a/wayland-client/src/lib.rs b/wayland-client/src/lib.rs index a96a0ec2876..9500c953ff6 100644 --- a/wayland-client/src/lib.rs +++ b/wayland-client/src/lib.rs @@ -6,9 +6,8 @@ //! proxies (objects implementing the [`Proxy`] trait), and the [`Dispatch`] trait. //! //! The [`Connection`] is the heart of this crate. It represents your connection to the Wayland server, and -//! you'll generally initialize it using the [`Connection::connect_to_env()`](Connection::connect_to_env) -//! method, which will attempt to open a Wayland connection following the configuration specified by the -//! environment. +//! you'll generally initialize it using the [`Connection::connect_to_env()`] method, which will +//! attempt to open a Wayland connection following the configuration specified by the ! environment. //! //! Once you have a [`Connection`], you can create an [`EventQueue`] from it. This [`EventQueue`] will take //! care of processing events from the Wayland server and delivering them to your processing logic, in the form @@ -140,7 +139,7 @@ //! APIs from `wayland-backend`, allowing you to register callbacks for those objects that will be invoked //! whenever they receive an event and *any* event queue from the program is being dispatched. Those //! callbacks are more constrained: they don't get a `&mut State` reference, and must be threadsafe. See -//! [`Proxy::send_constructor`] and [`ObjectData`](crate::backend::ObjectData) for details about how to +//! [`Proxy::send_constructor()`] and [`ObjectData`] for details about how to //! assign such callbacks to objects. //! //! ### Interaction with FFI @@ -152,8 +151,8 @@ //! it to your dependencies and enabling its `client_system` feature. //! //! - If you need to send pointers to FFI, you can retrive the `*mut wl_proxy` pointers from the proxies by -//! first getting the [`ObjectId`](crate::backend::ObjectId) using the [`Proxy::id()`] method, and then -//! using the `ObjectId::as_ptr()` method. +//! first getting the [`ObjectId`] using the [`Proxy::id()`] method, and then +//! using the [`ObjectId::as_ptr()`] method. // - If you need to receive pointers from FFI, you need to first create a // [`Backend`][backend::Backend] from the `*mut wl_display` using // [`Backend::from_external_display()`][backend::Backend::from_foreign_display()], and then @@ -253,7 +252,7 @@ pub trait Proxy: Clone + std::fmt::Debug + Sized { /// Access the raw data associated with this object. /// /// For objects created using the scanner-generated methods, this will be an instance of the - /// [QueueProxyData] type. + /// [`QueueProxyData`] type. fn object_data(&self) -> Option<&Arc>; /// Access the backend associated with this object @@ -277,13 +276,13 @@ pub trait Proxy: Clone + std::fmt::Debug + Sized { /// Send a request for this object. /// /// It is an error to use this function on requests that create objects; use - /// [Proxy::send_constructor] for such requests. + /// [`send_constructor()`][Self::send_constructor()] for such requests. fn send_request(&self, req: Self::Request<'_>) -> Result<(), InvalidId>; /// Send a request for this object that creates another object. /// /// It is an error to use this function on requests that do not create objects; use - /// [Proxy::send_request] for such requests. + /// [`send_request()`][Self::send_request()] for such requests. fn send_constructor( &self, req: Self::Request<'_>, diff --git a/wayland-cursor/src/lib.rs b/wayland-cursor/src/lib.rs index 280328bb998..02a9c02713c 100644 --- a/wayland-cursor/src/lib.rs +++ b/wayland-cursor/src/lib.rs @@ -9,7 +9,7 @@ //! //! First of all, you need to create a [`CursorTheme`], which represents the full cursor theme. //! -//! From this theme, using the [`get_cursor()`](CursorTheme::get_cursor) method, you can load a +//! From this theme, using the [`get_cursor()`][CursorTheme::get_cursor()] method, you can load a //! specific [`Cursor`], which can contain several images if the cursor is animated. It also provides //! you with the means of querying which frame of the animation should be displayed at what time, as //! well as handles to the buffers containing these frames, to attach them to a wayland surface. diff --git a/wayland-egl/src/lib.rs b/wayland-egl/src/lib.rs index 9e08ceac92a..d94e979871f 100644 --- a/wayland-egl/src/lib.rs +++ b/wayland-egl/src/lib.rs @@ -18,7 +18,7 @@ use wayland_sys::{client::wl_proxy, egl::*, ffi_dispatch}; /// Checks if the wayland-egl lib is available and can be used /// /// Trying to create an [`WlEglSurface`] while this function returns -/// `false` will result in a panic. +/// [`false`] will result in a panic. pub fn is_available() -> bool { is_lib_available() } @@ -26,7 +26,7 @@ pub fn is_available() -> bool { /// EGL surface /// /// This object is a simple wrapper around a `wl_surface` to add the EGL -/// capabilities. Just use the [`ptr()`](WlEglSurface::ptr) method once this object +/// capabilities. Just use the [`ptr()`][WlEglSurface::ptr()] method once this object /// is created to get the window pointer your OpenGL library is needing to initialize /// the EGL context (you'll most likely need the display ptr as well, that you can /// get via the [`ObjectId::as_ptr()`] method on of the `wl_display` ID). @@ -38,7 +38,7 @@ pub struct WlEglSurface { impl WlEglSurface { /// Create an EGL surface from a wayland surface /// - /// This method will check that the provided `ObjectId` is still alive and from the + /// This method will check that the provided [`ObjectId`] is still alive and from the /// correct interface (`wl_surface`). /// /// You must always destroy the [`WlEglSurface`] *before* the underling `wl_surface` diff --git a/wayland-server/src/client.rs b/wayland-server/src/client.rs index e98d67f52a8..b7ce805e6ed 100644 --- a/wayland-server/src/client.rs +++ b/wayland-server/src/client.rs @@ -72,8 +72,8 @@ impl Client { /// Create a new Wayland object in the protocol state of this client, from an [`ObjectData`] /// - /// This is a lower-level method than [`create_resource`](Client::create_resource), in case you need to - /// bypass the [`Dispatch`] machinnery. + /// This is a lower-level method than [`create_resource()`][Self::create_resource()], in case you need to + /// bypass the [`Dispatch`] machinery. /// /// The newly created resource should be immediately sent to the client through an associated event with /// a `new_id` argument. Not doing so risks corrupting the protocol state and causing protocol errors at diff --git a/wayland-server/src/dispatch.rs b/wayland-server/src/dispatch.rs index f68fc5b84dd..82217d89499 100644 --- a/wayland-server/src/dispatch.rs +++ b/wayland-server/src/dispatch.rs @@ -14,14 +14,14 @@ use crate::{Client, DisplayHandle, Resource}; /// ## General usage /// /// You need to implement this trait on your `State` for every type of Wayland object that will be processed -/// by the [`Display`](crate::Display) working with your `State`. +/// by the [`Display`][crate::Display] working with your `State`. /// /// You can have different implementations of the trait for the same interface but different `UserData` type, /// this way the events for a given object will be processed by the adequate implementation depending on /// which `UserData` was assigned to it at creation. /// /// The way this trait works is that the [`Dispatch::request()`] method will be invoked by the -/// [`Display`](crate::Display) for every request received by an object. Your implementation can then match +/// [`Display`][crate::Display] for every request received by an object. Your implementation can then match /// on the associated [`Resource::Request`] enum and do any processing needed with that event. /// /// If the request being processed created a new object, you'll receive it as a [`New`]. When that is the @@ -31,7 +31,7 @@ use crate::{Client, DisplayHandle, Resource}; /// /// To provide generic handlers for downstream usage, it is possible to make an implementation of the trait /// that is generic over the last type argument, as illustrated below. Users will then be able to -/// automatically delegate their implementation to yours using the [`delegate_dispatch!`] macro. +/// automatically delegate their implementation to yours using the [`crate::delegate_dispatch!()`] macro. /// /// As a result, when your implementation is instanciated, the last type parameter `State` will be the state /// struct of the app using your generic implementation. You can put additional trait constraints on it to @@ -105,7 +105,7 @@ pub trait Dispatch: Sized { /// Note this type only provides an immutable reference to the user data, you will need to use /// interior mutability to change it. /// - /// Typically a [`Mutex`](std::sync::Mutex) would be used to have interior mutability. + /// Typically a [`Mutex`][std::sync::Mutex] would be used to have interior mutability. /// /// You are given the [`ObjectId`] and [`ClientId`] associated with the destroyed object for cleanup /// convenience. @@ -145,7 +145,7 @@ impl New { /// Helper to initialize client-created objects /// -/// This helper is provided to you in your [`Dispatch`] and [`GlobalDispatch`](super::GlobalDispatch) to +/// This helper is provided to you in your [`Dispatch`] and [`GlobalDispatch`][super::GlobalDispatch] to /// initialize objects created by the client, by assigning them their user-data (or [`ObjectData`] if you /// need to go this lower-level route). /// @@ -176,8 +176,8 @@ impl<'a, D> DataInit<'a, D> { /// Set a custom [`ObjectData`] for this object /// /// This object data is not managed by `wayland-server`, as a result you will not - /// be able to retreive it through [`Resource::data()`](Resource::data). - /// Instead, you'll need to retrieve it using [`Resource::object_data()`](Resource::object_data) and + /// be able to retreive it through [`Resource::data()`]. + /// Instead, you'll need to retrieve it using [`Resource::object_data()`] and /// handle the downcasting yourself. pub fn custom_init( &mut self, @@ -192,7 +192,7 @@ impl<'a, D> DataInit<'a, D> { /// Post an error on an uninitialized object. /// - /// This is only meant to be used in [`GlobalDispatch`](crate::GlobalDispatch) where a global protocol + /// This is only meant to be used in [`GlobalDispatch`][crate::GlobalDispatch] where a global protocol /// object is instantiated. pub fn post_error( &mut self, @@ -301,7 +301,7 @@ impl + 'stati /// /// # Usage /// -/// For example, say you want to delegate events for [`WlOutput`](crate::protocol::wl_output::WlOutput) +/// For example, say you want to delegate events for [`WlOutput`][crate::protocol::wl_output::WlOutput] /// to the `DelegateToMe` type from the [`Dispatch`] documentation. /// /// ``` diff --git a/wayland-server/src/display.rs b/wayland-server/src/display.rs index fb1fcaa2329..324f08ff5f8 100644 --- a/wayland-server/src/display.rs +++ b/wayland-server/src/display.rs @@ -24,11 +24,11 @@ use crate::{ /// /// The main loop of a Wayland compositor generally needs to wait on several sources of events, using /// tools like `epoll` (on Linux). The Wayland display can be integrated in this mechanism by getting the -/// file descriptor as from [`.backend()`](Display::backend)[`.poll_fd()`](Backend::poll_fd) and invoking -/// the [`dispatch_clients()`](Display::dispatch_clients) method whenever it becomes readable. +/// file descriptor as from [`.backend()`][Self::backend()][`.poll_fd()`][Backend::poll_fd()] and invoking +/// the [`dispatch_clients()`][Self::dispatch_clients()] method whenever it becomes readable. /// /// To ensure all clients receive the events your compositor sends them, you also need to regularly invoke -/// the [`flush_clients()`](Display::flush_clients) method, which will write the outgoing buffers into the +/// the [`flush_clients()`][Self::flush_clients()] method, which will write the outgoing buffers into the /// sockets. #[derive(Debug)] pub struct Display { @@ -153,7 +153,7 @@ impl DisplayHandle { /// with this global is freed, meaning clients trying to bind it will receive a protocol error. /// /// When removing a global, it is recommended to first disable it using - /// [`disable_global()`](DisplayHandle::disable_global) to allow some time for clients to register that + /// [`disable_global()`][Self::disable_global()] to allow some time for clients to register that /// the global is getting removed, to avoid a race where a client would be killed because it bound a global /// at the same as the server decided to remove it. After the global has been disabled for some time (like /// a few seconds) it should be safe to actually remove it. @@ -208,7 +208,7 @@ impl DisplayHandle { } impl From for DisplayHandle { - /// Creates a [`DisplayHandle`] using a [`Handle`](Handle) from `wayland-backend`. + /// Creates a [`DisplayHandle`] using a [`Handle`] from `wayland-backend`. fn from(handle: Handle) -> Self { Self { handle } } diff --git a/wayland-server/src/global.rs b/wayland-server/src/global.rs index 42835c0b4b7..f6a2647e91a 100644 --- a/wayland-server/src/global.rs +++ b/wayland-server/src/global.rs @@ -91,7 +91,7 @@ impl ObjectData for ProtocolErrorData { /// A trait which provides an implementation for handling advertisement of a global to clients with some type /// of associated user data. /// -/// Its behavior is similar to the [`Dispatch`](crate::Dispatch) trait. +/// Its behavior is similar to the [`Dispatch`][crate::Dispatch] trait. pub trait GlobalDispatch: Sized { /// Called when a client has bound this global. /// @@ -128,7 +128,7 @@ pub trait GlobalDispatch: Sized { /// A helper macro which delegates a set of [`GlobalDispatch`] implementations for a resource to some other type which /// provdes a generic [`GlobalDispatch`] implementation. /// -/// Its usage is similar to the [`delegate_dispatch!`](crate::delegate_dispatch) macro. +/// Its usage is similar to the [`crate::delegate_dispatch!()`] macro. #[macro_export] macro_rules! delegate_global_dispatch { ($(@< $( $lt:tt $( : $clt:tt $(+ $dlt:tt )* )? ),+ >)? $dispatch_from:ty : [$interface: ty: $udata: ty] => $dispatch_to: ty) => { diff --git a/wayland-server/src/lib.rs b/wayland-server/src/lib.rs index 60f2dc3b738..69e9f60487a 100644 --- a/wayland-server/src/lib.rs +++ b/wayland-server/src/lib.rs @@ -24,7 +24,7 @@ //! `Dispatch` for every Wayland object `O` it needs to process events for. //! //! However, implementing all those traits on your own is a lot of (often uninteresting) work. To make this -//! easier a composition mechanism is provided using the [`delegate_dispatch!`] macro. This way, another +//! easier a composition mechanism is provided using the [`delegate_dispatch!()`] macro. This way, another //! library (such as Smithay) can provide generic [`Dispatch`] implementations that you can reuse on your //! own app by delegating those objects to that provided implementation. See the documentation of those //! traits and macro for details. @@ -49,7 +49,7 @@ //! It may be that for some of your objects, handling them via the [`Dispatch`] trait is impractical. In //! those contexts, this crate also provides some escape-hatches to directly interface with the low-level //! APIs from `wayland-backend`, allowing you to register callbacks for those objects by directly providing -//! implementations of the backend [`ObjectData`](crate::backend::ObjectData) trait. +//! implementations of the backend [`ObjectData`][backend::ObjectData] trait. //! See [`Client::create_resource_from_objdata()`] and [`DataInit::custom_init()`]. //! //! ### Interaction with FFI @@ -63,14 +63,14 @@ //! Then, you'll generally need: //! //! - The `*mut wl_display` pointer, that you can retrieve by first retrieving the -//! [`Backend`](crate::backend::Backend) using [`Display::backend()`], and then invoke +//! [`Backend`][backend::Backend] using [`Display::backend()`], and then invoke //! [`.handle()`][backend::Backend::handle()][`.display_ptr()`][backend::Handle::display_ptr()]. //! - The `*mut wl_resource` pointers for the objects you need to share, by first getting the -//! [`ObjectId`](crate::backend::ObjectId) using the [`Resource::id()`] method, and then -//! the `ObjectId::as_ptr()` method. +//! [`ObjectId`] using the [`Resource::id()`] method, and then +//! the [`ObjectId::as_ptr()`] method. //! //! If you need to receive pointers from FFI, you can make [`ObjectId`]s from the `*mut wl_resource` pointers -//! using `ObjectId::from_ptr()`, and then make the resources using [`Resource::from_id`]. +//! using [`ObjectId::from_ptr()`], and then make the resources using [`Resource::from_id()`]. #![forbid(improper_ctypes, unsafe_op_in_unsafe_fn)] // Doc feature labels can be tested locally by running RUSTDOCFLAGS="--cfg=docsrs" cargo +nightly doc -p #![cfg_attr(docsrs, feature(doc_auto_cfg))] diff --git a/wayland-server/src/socket.rs b/wayland-server/src/socket.rs index 73fc787cfb2..37694f766a1 100644 --- a/wayland-server/src/socket.rs +++ b/wayland-server/src/socket.rs @@ -46,7 +46,7 @@ impl ListeningSocket { /// Attempt to bind a listening socket from a sequence of names /// - /// This method will repeatedly try to bind sockets in teh form `{basename}-{n}` for values of `n` + /// This method will repeatedly try to bind sockets in the form `{basename}-{n}` for values of `n` /// yielded from the provided range and returns the first one that succeeds. /// /// This method will acquire an associate lockfile. The socket will be created in the @@ -154,8 +154,8 @@ impl ListeningSocket { /// Returns the name of the listening socket. /// - /// Will only be [`Some`] if that socket was created with [`bind`](ListeningSocket::bind) or - /// [`bind_auto`](ListeningSocket::bind_auto). + /// Will only be [`Some`] if that socket was created with [`bind()`][Self::bind()] or + /// [`bind_auto()`][Self::bind_auto()]. pub fn socket_name(&self) -> Option<&OsStr> { self.socket_name.as_deref() } @@ -167,7 +167,7 @@ impl AsRawFd for ListeningSocket { /// This file descriptor may be polled using apis such as epoll and kqueue to be told when a client has /// found the socket and is trying to connect. /// - /// When the polling system reports the file descriptor is ready, you can use [`ListeningSocket::accept`] + /// When the polling system reports the file descriptor is ready, you can use [`accept()`][Self::accept()] /// to get a stream to the new client. fn as_raw_fd(&self) -> RawFd { self.listener.as_raw_fd() @@ -180,7 +180,7 @@ impl AsFd for ListeningSocket { /// This file descriptor may be polled using apis such as epoll and kqueue to be told when a client has /// found the socket and is trying to connect. /// - /// When the polling system reports the file descriptor is ready, you can use [`ListeningSocket::accept`] + /// When the polling system reports the file descriptor is ready, you can use [`accept()`][Self::accept()] /// to get a stream to the new client. fn as_fd(&self) -> BorrowedFd<'_> { self.listener.as_fd()