Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix redundant/broken intradoc links and minor cleanup #716

Merged
merged 13 commits into from
May 20, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
45 changes: 25 additions & 20 deletions wayland-backend/src/client_api.rs
Original file line number Diff line number Diff line change
@@ -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;
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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()
Expand All @@ -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()
Expand All @@ -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 {
Expand All @@ -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 })
}
Expand All @@ -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()
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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> {
Expand All @@ -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()
Expand All @@ -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.
Expand All @@ -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()
Expand Down
6 changes: 3 additions & 3 deletions wayland-backend/src/debug.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

use std::{
fmt::Display,
os::unix::prelude::AsRawFd,
os::unix::io::AsRawFd,
time::{SystemTime, UNIX_EPOCH},
};

Expand All @@ -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,
Expand All @@ -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,
Expand Down
6 changes: 3 additions & 3 deletions wayland-backend/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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),* $(,)?] $(,)?) => {
Expand Down
2 changes: 1 addition & 1 deletion wayland-backend/src/protocol.rs
Original file line number Diff line number Diff line change
@@ -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};

Expand Down
3 changes: 1 addition & 2 deletions wayland-backend/src/rs/client_impl/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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},
Expand Down
4 changes: 2 additions & 2 deletions wayland-backend/src/rs/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
6 changes: 4 additions & 2 deletions wayland-backend/src/rs/server_impl/client.rs
Original file line number Diff line number Diff line change
@@ -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,
};

Expand Down
3 changes: 1 addition & 2 deletions wayland-backend/src/rs/server_impl/common_poll.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
use std::{
os::unix::io::AsRawFd,
os::unix::io::{BorrowedFd, OwnedFd},
os::unix::io::{AsRawFd, BorrowedFd, OwnedFd},
sync::{Arc, Mutex},
};

Expand Down
6 changes: 4 additions & 2 deletions wayland-backend/src/rs/server_impl/handle.rs
Original file line number Diff line number Diff line change
@@ -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},
};

Expand Down
3 changes: 1 addition & 2 deletions wayland-backend/src/rs/socket.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
3 changes: 1 addition & 2 deletions wayland-backend/src/rs/wire.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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};

Expand Down
14 changes: 8 additions & 6 deletions wayland-backend/src/server_api.rs
Original file line number Diff line number Diff line change
@@ -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,
};

Expand Down Expand Up @@ -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 {
Expand All @@ -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 })
Expand Down Expand Up @@ -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,
Expand Down
3 changes: 1 addition & 2 deletions wayland-backend/src/sys/client_impl/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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::{
Expand Down
Loading
Loading