From 04aee7cbc9de404ed4ec96d617cbec9a5d9e9723 Mon Sep 17 00:00:00 2001 From: Victor Brekenfeld Date: Sat, 8 Dec 2018 13:40:07 +0100 Subject: [PATCH] Replace documentation links with intra rustdoc links --- .travis.yml | 2 +- src/backend/drm/egl/error.rs | 3 +- src/backend/drm/egl/mod.rs | 10 +- src/backend/drm/egl/session.rs | 8 +- src/backend/drm/gbm/egl.rs | 8 +- src/backend/drm/gbm/error.rs | 3 +- src/backend/drm/gbm/mod.rs | 8 +- src/backend/drm/gbm/session.rs | 8 +- src/backend/drm/gbm/surface.rs | 10 +- src/backend/drm/legacy/error.rs | 3 +- src/backend/drm/legacy/mod.rs | 6 +- src/backend/drm/legacy/session.rs | 8 +- src/backend/drm/mod.rs | 54 ++++---- src/backend/egl/context.rs | 6 +- src/backend/egl/mod.rs | 48 +++---- src/backend/egl/native.rs | 18 +-- src/backend/graphics/cursor.rs | 9 +- src/backend/graphics/gl.rs | 8 +- src/backend/graphics/glium.rs | 10 +- src/backend/input.rs | 74 +++++------ src/backend/libinput.rs | 18 +-- src/backend/session/auto.rs | 64 ++++++---- src/backend/session/dbus/logind.rs | 141 +++++++++++---------- src/backend/session/direct.rs | 133 +++++++++---------- src/backend/session/mod.rs | 15 ++- src/backend/session/multi.rs | 6 +- src/backend/udev.rs | 24 ++-- src/backend/winit.rs | 101 ++++++++------- src/lib.rs | 2 +- src/wayland/compositor/mod.rs | 46 ++++--- src/wayland/compositor/roles.rs | 19 +-- src/wayland/data_device/mod.rs | 30 +++-- src/wayland/data_device/server_dnd_grab.rs | 2 +- src/wayland/mod.rs | 2 +- src/wayland/output/mod.rs | 12 +- src/wayland/seat/keyboard.rs | 11 +- src/wayland/seat/mod.rs | 15 ++- src/wayland/seat/pointer.rs | 11 +- src/wayland/shell/legacy/mod.rs | 10 +- src/wayland/shell/xdg/mod.rs | 31 +++-- src/wayland/shm/mod.rs | 9 +- 41 files changed, 529 insertions(+), 477 deletions(-) diff --git a/.travis.yml b/.travis.yml index dad47e6..284b692 100644 --- a/.travis.yml +++ b/.travis.yml @@ -108,7 +108,7 @@ deploy: local_dir: "./target/doc" on: branch: master - rust: stable + rust: nightly condition: "$FEATURES = all" notifications: diff --git a/src/backend/drm/egl/error.rs b/src/backend/drm/egl/error.rs index 07f0e94..f55ccff 100644 --- a/src/backend/drm/egl/error.rs +++ b/src/backend/drm/egl/error.rs @@ -1,5 +1,6 @@ //! -//! Errors thrown by the `DrmDevice` and `DrmBackend` +//! Errors thrown by the [`EglDevice`](::backend::drm::egl::EglDevice) +//! and [`EglSurface`](::backend::drm::egl::EglSurface). //! use backend::egl::error as egl; diff --git a/src/backend/drm/egl/mod.rs b/src/backend/drm/egl/mod.rs index b918427..fec2968 100644 --- a/src/backend/drm/egl/mod.rs +++ b/src/backend/drm/egl/mod.rs @@ -1,9 +1,9 @@ //! -//! [`Device`](../trait.Device.html) and [`Surface`](../trait.Surface.html) +//! [`Device`](Device) and [`Surface`](Surface) //! implementations using egl contexts and surfaces for efficient rendering. //! -//! Usually this implementation's [`EglSurface`](struct.EglSurface.html)s implementation -//! of [`GlGraphicsBackend`](../../graphics/gl/trait.GlGraphicsBackend.html) will be used +//! Usually this implementation's [`EglSurface`](::backend::drm::egl::EglSurface)s implementation +//! of [`GLGraphicsBackend`](::backend::graphics::gl::GLGraphicsBackend) will be used //! to let your compositor render. //! Take a look at `anvil`s source code for an example of this. //! @@ -59,7 +59,7 @@ where D: Device + NativeDisplay + 'static, ::Surface: NativeSurface, { - /// Try to create a new `EglDevice` from an open device. + /// Try to create a new [`EglDevice`] from an open device. /// /// Returns an error if the file is no valid device or context /// creation was not successful. @@ -79,7 +79,7 @@ where ) } - /// Create a new `EglDevice` from an open device and given `GlAttributes` + /// Create a new [`EglDevice`] from an open device and given [`GlAttributes`] /// /// Returns an error if the file is no valid device or context /// creation was not successful. diff --git a/src/backend/drm/egl/session.rs b/src/backend/drm/egl/session.rs index 0d6fc3f..aa8d213 100644 --- a/src/backend/drm/egl/session.rs +++ b/src/backend/drm/egl/session.rs @@ -1,6 +1,6 @@ //! -//! Support to register an [`EglDevice`](../struct.EglDevice.html) -//! to an open [`Session`](../../session/trait.Session.html). +//! Support to register an [`EglDevice`](EglDevice) +//! to an open [`Session`](::backend::session::Session). //! use drm::control::crtc; @@ -11,8 +11,8 @@ use backend::drm::Device; use backend::egl::native::{Backend, NativeDisplay, NativeSurface}; use backend::session::{AsSessionObserver, SessionObserver}; -/// [`SessionObserver`](../../session/trait.SessionObserver.html) -/// linked to the [`EglDevice`](../struct.EglDevice.html) it was +/// [`SessionObserver`](SessionObserver) +/// linked to the [`EglDevice`](EglDevice) it was /// created from. pub struct EglDeviceObserver { observer: S, diff --git a/src/backend/drm/gbm/egl.rs b/src/backend/drm/gbm/egl.rs index 5977870..a479d0b 100644 --- a/src/backend/drm/gbm/egl.rs +++ b/src/backend/drm/gbm/egl.rs @@ -1,7 +1,7 @@ //! -//! Egl [`NativeDisplay`](../../egl/native/trait.NativeDisplay.html) and -//! [`NativeSurface`](../../egl/native/trait.NativeSurface.html) support for -//! [`GbmDevice`](../struct.GbmDevice.html) and [`GbmSurface`](../struct.GbmSurface.html). +//! Egl [`NativeDisplay`](::backend::egl::native::NativeDisplay) and +//! [`NativeSurface`](::backend::egl::native::NativeSurface) support for +//! [`GbmDevice`](GbmDevice) and [`GbmSurface`](GbmSurface). //! use backend::drm::{Device, RawDevice}; @@ -20,7 +20,7 @@ use std::ptr; /// Egl Gbm backend type /// -/// See [`Backend`](../../egl/native/trait.Backend.html). +/// See [`Backend`](::backend::egl::native::Backend). pub struct Gbm { _userdata: PhantomData, } diff --git a/src/backend/drm/gbm/error.rs b/src/backend/drm/gbm/error.rs index 452e657..46aad9d 100644 --- a/src/backend/drm/gbm/error.rs +++ b/src/backend/drm/gbm/error.rs @@ -1,5 +1,6 @@ //! -//! Errors thrown by the `DrmDevice` and `DrmBackend` +//! Errors thrown by the [`GbmDevice`](::backend::drm::gbm::GbmDevice) +//! and [`GbmSurface`](::backend::drm::gbm::GbmSurface). //! error_chain! { diff --git a/src/backend/drm/gbm/mod.rs b/src/backend/drm/gbm/mod.rs index 7298d7c..af25d00 100644 --- a/src/backend/drm/gbm/mod.rs +++ b/src/backend/drm/gbm/mod.rs @@ -1,12 +1,12 @@ //! -//! [`Device`](../trait.Device.html) and [`Surface`](../trait.Surface.html) +//! [`Device`](Device) and [`Surface`](Surface) //! implementations using gbm buffers for efficient rendering. //! -//! Usually this implementation will be wrapped into a [`EglDevice`](../egl/struct.EglDevice.html). +//! Usually this implementation will be wrapped into a [`EglDevice`](::backend::drm::egl::EglDevice). //! Take a look at `anvil`s source code for an example of this. //! //! To use these types standalone, you will need to consider the special requirements -//! of [`GbmSurface::page_flip`](struct.GbmSurface.html#method.page_flip). +//! of [`GbmSurface::page_flip`](::backend::drm::gbm::GbmSurface::page_flip). //! use super::{Device, DeviceHandler, RawDevice, ResourceHandles, ResourceInfo, Surface}; @@ -44,7 +44,7 @@ pub struct GbmDevice { } impl GbmDevice { - /// Create a new `GbmDevice` from an open drm node + /// Create a new [`GbmDevice`] from an open drm node /// /// Returns an error if the file is no valid drm node or context creation was not /// successful. diff --git a/src/backend/drm/gbm/session.rs b/src/backend/drm/gbm/session.rs index 0777cf4..9f0c135 100644 --- a/src/backend/drm/gbm/session.rs +++ b/src/backend/drm/gbm/session.rs @@ -1,6 +1,6 @@ //! -//! Support to register a [`GbmDevice`](../struct.GbmDevice.html) -//! to an open [`Session`](../../session/trait.Session.html). +//! Support to register a [`GbmDevice`](GbmDevice) +//! to an open [`Session`](::backend::session::Session). //! use drm::control::{crtc, Device as ControlDevice, ResourceInfo}; @@ -14,8 +14,8 @@ use super::{GbmDevice, GbmSurfaceInternal}; use backend::drm::{RawDevice, RawSurface}; use backend::session::{AsSessionObserver, SessionObserver}; -/// [`SessionObserver`](../../session/trait.SessionObserver.html) -/// linked to the [`GbmDevice`](../struct.GbmDevice.html) it was +/// [`SessionObserver`](SessionObserver) +/// linked to the [`GbmDevice`](GbmDevice) it was /// created from. pub struct GbmDeviceObserver< S: SessionObserver + 'static, diff --git a/src/backend/drm/gbm/surface.rs b/src/backend/drm/gbm/surface.rs index 62a7ea2..c1b99be 100644 --- a/src/backend/drm/gbm/surface.rs +++ b/src/backend/drm/gbm/surface.rs @@ -287,9 +287,9 @@ impl GbmSurface { /// Flips the underlying buffers. /// /// The surface will report being already flipped until the matching event - /// was processed either by calling `GbmDevice::process_events` manually after the flip + /// was processed either by calling [`Device::process_events`] manually after the flip /// (bad idea performance-wise) or by binding the device to an event-loop by using - /// `device_bind`. + /// [`device_bind`](::backend::drm::device_bind). /// /// *Note*: This might trigger a full modeset on the underlying device, /// potentially causing some flickering. In that case this operation is @@ -301,9 +301,9 @@ impl GbmSurface { /// Recreate underlying gbm resources. /// /// This recreates the gbm surfaces resources, which might be needed after e.g. - /// calling [`Surface::use_mode`](../trait.Surface.html#method.use_mode). - /// You may check if your `GbmSurface` needs recreation through - /// [`needs_recreation`](#method.needs_recreation). + /// calling [`Surface::use_mode`](Surface::use_mode). + /// You may check if your [`GbmSurface`] needs recreation through + /// [`needs_recreation`](GbmSurface::needs_recreation). pub fn recreate(&self) -> Result<()> { self.0.recreate() } diff --git a/src/backend/drm/legacy/error.rs b/src/backend/drm/legacy/error.rs index 4e14eaf..d657194 100644 --- a/src/backend/drm/legacy/error.rs +++ b/src/backend/drm/legacy/error.rs @@ -1,5 +1,6 @@ //! -//! Errors thrown by the `LegacyDrmDevice` and `LegacyDrmSurface` +//! Errors thrown by the [`LegacyDrmDevice`](::backend::drm::legacy::LegacyDrmDevice) +//! and [`LegacyDrmSurface`](::backend::drm::legacy::LegacyDrmSurface). //! use drm::control::{connector, crtc, Mode}; diff --git a/src/backend/drm/legacy/mod.rs b/src/backend/drm/legacy/mod.rs index e37cd20..fadcaa4 100644 --- a/src/backend/drm/legacy/mod.rs +++ b/src/backend/drm/legacy/mod.rs @@ -1,8 +1,8 @@ //! -//! [`RawDevice`](../trait.RawDevice.html) and [`RawSurface`](../trait.RawSurface.html) +//! [`RawDevice`](RawDevice) and [`RawSurface`](RawSurface) //! implementations using the legacy mode-setting infrastructure. //! -//! Usually this implementation will be wrapped into a [`GbmDevice`](../gbm/struct.GbmDevice.html). +//! Usually this implementation will be wrapped into a [`GbmDevice`](::backend::drm::gbm::GbmDevice). //! Take a look at `anvil`s source code for an example of this. //! //! For an example how to use this standalone, take a look at the `raw_drm` example. @@ -86,7 +86,7 @@ impl Drop for Dev { } impl LegacyDrmDevice { - /// Create a new `LegacyDrmDevice` from an open drm node + /// Create a new [`LegacyDrmDevice`] from an open drm node /// /// Returns an error if the file is no valid drm node or context creation was not /// successful. diff --git a/src/backend/drm/legacy/session.rs b/src/backend/drm/legacy/session.rs index fcb7b55..3ba2077 100644 --- a/src/backend/drm/legacy/session.rs +++ b/src/backend/drm/legacy/session.rs @@ -1,6 +1,6 @@ //! -//! Support to register an open [`LegacyDrmDevice`](../struct.LegacyDrmDevice.html) -//! to an open [`Session`](../../session/trait.Session.html). +//! Support to register an open [`LegacyDrmDevice`](LegacyDrmDevice) +//! to an open [`Session`](::backend::session::Session). //! use drm::control::crtc; @@ -17,8 +17,8 @@ use std::sync::Arc; use super::{Dev, LegacyDrmDevice, LegacyDrmSurfaceInternal}; use backend::session::{AsSessionObserver, SessionObserver}; -/// [`SessionObserver`](../../session/trait.SessionObserver.html) -/// linked to the [`LegacyDrmDevice`](../struct.LegacyDrmDevice.html) +/// [`SessionObserver`](SessionObserver) +/// linked to the [`LegacyDrmDevice`](LegacyDrmDevice) /// it was created from. pub struct LegacyDrmDeviceObserver { dev: Weak>, diff --git a/src/backend/drm/mod.rs b/src/backend/drm/mod.rs index 8a143b0..13a2e41 100644 --- a/src/backend/drm/mod.rs +++ b/src/backend/drm/mod.rs @@ -63,11 +63,11 @@ pub mod gbm; #[cfg(feature = "backend_drm_legacy")] pub mod legacy; -/// Trait to receive events of a bound [`Device`](trait.Device.html) +/// Trait to receive events of a bound [`Device`] /// -/// See [`device_bind`](fn.device_bind.html) +/// See [`device_bind`] pub trait DeviceHandler { - /// The [`Device`](trait.Device.html) type this handler can handle + /// The [`Device`] type this handler can handle type Device: Device + ?Sized; /// A vblank blank event on the provided crtc has happend @@ -78,15 +78,15 @@ pub trait DeviceHandler { /// An open drm device pub trait Device: AsRawFd + DevPath { - /// Associated [`Surface`](trait.Surface.html) of this `Device` type + /// Associated [`Surface`] of this [`Device`] type type Surface: Surface; - /// Returns the `id` of this device node. + /// Returns the id of this device node. fn device_id(&self) -> dev_t; - /// Assigns a `DeviceHandler` called during event processing. + /// Assigns a [`DeviceHandler`] called during event processing. /// - /// See [`device_bind`](fn.device_bind.html) and [`DeviceHandler`](trait.DeviceHandler.html) + /// See [`device_bind`] and [`DeviceHandler`] fn set_handler(&mut self, handler: impl DeviceHandler + 'static); /// Clear a set [`DeviceHandler`](trait.DeviceHandler.html), if any fn clear_handler(&mut self); @@ -108,26 +108,26 @@ pub trait Device: AsRawFd + DevPath { /// Processes any open events of the underlying file descriptor. /// /// You should not call this function manually, but rather use - /// [`device_bind`](fn.device_bind.html) to register the device + /// [`device_bind`] to register the device /// to an [`EventLoop`](https://docs.rs/calloop/0.4.2/calloop/struct.EventLoop.html) /// to synchronize your rendering to the vblank events of the open crtc's fn process_events(&mut self); - /// Load the resource from a `Device` given its + /// Load the resource from a [`Device`] given its /// [`ResourceHandle`](https://docs.rs/drm/0.3.4/drm/control/trait.ResourceHandle.html) fn resource_info( &self, handle: T::Handle, ) -> Result::Error>; - /// Attempts to acquire a copy of the `Device`'s + /// Attempts to acquire a copy of the [`Device`]'s /// [`ResourceHandles`](https://docs.rs/drm/0.3.4/drm/control/struct.ResourceHandles.html) fn resource_handles(&self) -> Result::Error>; } -/// Marker trait for `Device`s able to provide [`RawSurface`](trait.RawSurface.html)s +/// Marker trait for [`Device`]s able to provide [`RawSurface`]s pub trait RawDevice: Device::Surface> { - /// Associated [`RawSurface`](trait.RawSurface.html) of this `RawDevice` type + /// Associated [`RawSurface`] of this [`RawDevice`] type type Surface: RawSurface; } @@ -135,8 +135,8 @@ pub trait RawDevice: Device::Surface> { pub trait Surface { /// Type repesenting a collection of /// [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s - /// returned by [`current_connectors`](#method.current_connectors) and - /// [`pending_connectors`](#method.pending_connectors) + /// returned by [`current_connectors`](Surface::current_connectors) and + /// [`pending_connectors`](Surface::pending_connectors) type Connectors: IntoIterator; /// Error type returned by methods of this trait type Error: Error + Send; @@ -146,10 +146,10 @@ pub trait Surface { /// Currently used [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s of this `Surface` fn current_connectors(&self) -> Self::Connectors; /// Returns the pending [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s - /// used after the next `commit` of this `Surface` + /// used after the next [`commit`](RawSurface::commit) of this [`Surface`] /// - /// *Note*: Only on a [`RawSurface`](trait.RawSurface.html) you may directly trigger - /// a [`commit`](trait.RawSurface.html#method.commit). Other `Surface`s provide their + /// *Note*: Only on a [`RawSurface`] you may directly trigger + /// a [`commit`](RawSurface::commit). Other `Surface`s provide their /// own methods that *may* trigger a commit, you will need to read their docs. fn pending_connectors(&self) -> Self::Connectors; /// Tries to add a new [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html) @@ -177,8 +177,8 @@ pub trait Surface { /// [`crtc`](https://docs.rs/drm/0.3.4/drm/control/crtc/index.html) or any of the /// pending [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s. /// - /// *Note*: Only on a [`RawSurface`](trait.RawSurface.html) you may directly trigger - /// a [`commit`](trait.RawSurface.html#method.commit). Other `Surface`s provide their + /// *Note*: Only on a [`RawSurface`] you may directly trigger + /// a [`commit`](RawSurface::commit). Other [`Surface`]s provide their /// own methods that *may* trigger a commit, you will need to read their docs. fn use_mode(&self, mode: Option) -> Result<(), Self::Error>; } @@ -188,15 +188,15 @@ pub trait RawSurface: Surface + ControlDevice + BasicDevice { /// Returns true whenever any state changes are pending to be commited /// /// The following functions may trigger a pending commit: - /// - [`add_connector`](trait.Surface.html#method.add_connector) - /// - [`remove_connector`](trait.Surface.html#method.remove_connector) - /// - [`use_mode`](trait.Surface.html#method.use_mode) + /// - [`add_connector`](Surface::add_connector) + /// - [`remove_connector`](Surface::remove_connector) + /// - [`use_mode`](Surface::use_mode) fn commit_pending(&self) -> bool; /// Commit the pending state rendering a given framebuffer. /// /// *Note*: This will trigger a full modeset on the underlying device, /// potentially causing some flickering. Check before performing this - /// operation if a commit really is necessary using [`commit_pending`](#method.commit_pending). + /// operation if a commit really is necessary using [`commit_pending`](RawSurface::commit_pending). /// /// This operation is blocking until the crtc is in the desired state. fn commit(&self, framebuffer: framebuffer::Handle) -> Result<(), ::Error>; @@ -206,8 +206,8 @@ pub trait RawSurface: Surface + ControlDevice + BasicDevice { /// This will not cause the crtc to modeset. /// /// This operation is not blocking and will produce a `vblank` event once swapping is done. - /// Make sure to [set a `DeviceHandler`](trait.Device.html#method.set_handler) and - /// [register the belonging `Device`](fn.device_bind.html) before to receive the event in time. + /// Make sure to [set a `DeviceHandler`](Device::set_handler) and + /// [register the belonging `Device`](device_bind) before to receive the event in time. fn page_flip(&self, framebuffer: framebuffer::Handle) -> Result<(), SwapBuffersError>; } @@ -225,10 +225,10 @@ impl DevPath for A { } } -/// Bind a `Device` to an `EventLoop`, +/// Bind a `Device` to an [`EventLoop`](wayland_server::calloop::EventLoop), /// /// This will cause it to recieve events and feed them into a previously -/// set [`DeviceHandler`](trait.DeviceHandler.html). +/// set [`DeviceHandler`](DeviceHandler). pub fn device_bind( handle: &LoopHandle, device: D, diff --git a/src/backend/egl/context.rs b/src/backend/egl/context.rs index f0767db..7133899 100644 --- a/src/backend/egl/context.rs +++ b/src/backend/egl/context.rs @@ -26,7 +26,7 @@ pub struct EGLContext> { } impl> EGLContext { - /// Create a new `EGLContext` from a given `NativeDisplay` + /// Create a new [`EGLContext`] from a given [`NativeDisplay`](native::NativeDisplay) pub fn new( native: N, attributes: GlAttributes, @@ -449,7 +449,7 @@ impl> EGLContext { /// Borrow the underlying native display. /// - /// This follows the same semantics as `std::cell:RefCell`. + /// This follows the same semantics as [`std::cell:RefCell`](std::cell::RefCell). /// Multiple read-only borrows are possible. Borrowing the /// backend while there is a mutable reference will panic. pub fn borrow(&self) -> Ref { @@ -458,7 +458,7 @@ impl> EGLContext { /// Borrow the underlying native display mutably. /// - /// This follows the same semantics as `std::cell:RefCell`. + /// This follows the same semantics as [`std::cell:RefCell`](std::cell::RefCell). /// Holding any other borrow while trying to borrow the backend /// mutably will panic. Note that EGL will borrow the display /// mutably during surface creation. diff --git a/src/backend/egl/mod.rs b/src/backend/egl/mod.rs index c5d29bd..d68f5cd 100644 --- a/src/backend/egl/mod.rs +++ b/src/backend/egl/mod.rs @@ -1,21 +1,22 @@ //! Common traits and types for egl rendering //! //! Large parts of this module are taken from -//! https://github.com/tomaka/glutin/tree/044e651edf67a2029eecc650dd42546af1501414/src/api/egl/ +//! [glutin src/api/egl](https://github.com/tomaka/glutin/tree/044e651edf67a2029eecc650dd42546af1501414/src/api/egl/) //! -//! It therefore falls under glutin's Apache 2.0 license -//! (see https://github.com/tomaka/glutin/tree/044e651edf67a2029eecc650dd42546af1501414/LICENSE) -//! Wayland specific EGL functionality - EGL based `WlBuffer`s. +//! It therefore falls under +//! [glutin's Apache 2.0 license](https://github.com/tomaka/glutin/tree/044e651edf67a2029eecc650dd42546af1501414/LICENSE) +//! +//! Wayland specific EGL functionality - EGL based [`WlBuffer`](wayland_server::protocol::wl_buffer::WlBuffer)s. //! //! The types of this module can be used to initialize hardware acceleration rendering -//! based on EGL for clients as it may enabled usage of `EGLImage` based `WlBuffer`s. +//! based on EGL for clients as it may enabled usage of `EGLImage` based [`WlBuffer`](wayland_server::protocol::wl_buffer::WlBuffer)s. //! -//! To use it bind any backend implementing the `EGLWaylandExtensions` trait, that shall do the -//! rendering (so pick a fast one), to the `wayland_server::Display` of your compositor. -//! Note only one backend may be bound to any `Display` at any time. +//! To use it bind any backend implementing the [`EGLGraphicsBackend`](::backend::egl::EGLGraphicsBackend) trait, that shall do the +//! rendering (so pick a fast one), to the [`wayland_server::Display`] of your compositor. +//! Note only one backend may be bound to any [`Display`](wayland_server::Display) at any time. //! -//! You may then use the resulting `EGLDisplay` to receive `EGLImages` of an EGL-based `WlBuffer` -//! for rendering. +//! You may then use the resulting [`EGLDisplay`](::backend::egl::EGLDisplay) to receive [`EGLImages`](::backend::egl::EGLImages) +//! of an EGL-based [`WlBuffer`](wayland_server::protocol::wl_buffer::WlBuffer) for rendering. #[cfg(feature = "renderer_gl")] use backend::graphics::gl::ffi as gl_ffi; @@ -219,7 +220,7 @@ impl Format { } } -/// Images of the EGL-based `WlBuffer`. +/// Images of the EGL-based [`WlBuffer`]. pub struct EGLImages { display: Weak, /// Width in pixels @@ -297,29 +298,28 @@ impl Drop for EGLImages { } } -/// Trait any backend type may implement that allows binding a `wayland_server::Display` -/// to create an `EGLDisplay` for EGL-based `WlBuffer`s. +/// Trait any backend type may implement that allows binding a [`Display`](wayland_server::Display) +/// to create an [`EGLDisplay`] for EGL-based [`WlBuffer`]s. #[cfg(feature = "native_lib")] pub trait EGLGraphicsBackend { /// Binds this EGL context to the given Wayland display. /// /// This will allow clients to utilize EGL to create hardware-accelerated - /// surfaces. The server will need to be able to handle EGL-`wl_buffers`. - /// See the `wayland::drm` module. + /// surfaces. The server will need to be able to handle EGL-[`WlBuffer`]s. /// /// ## Errors /// - /// This might return `WlExtensionNotSupported` if binding is not supported - /// by the EGL implementation. + /// This might return [`EglExtensionNotSupported`](ErrorKind::EglExtensionNotSupported) + /// if binding is not supported by the EGL implementation. /// - /// This might return `OtherEGLDisplayAlreadyBound` if called for the same - /// `Display` multiple times, as only one context may be bound at any given time. + /// This might return [`OtherEGLDisplayAlreadyBound`](ErrorKind::OtherEGLDisplayAlreadyBound) + /// if called for the same [`Display`] multiple times, as only one context may be bound at any given time. fn bind_wl_display(&self, display: &Display) -> Result; } -/// Type to receive `EGLImages` for EGL-based `WlBuffer`s. +/// Type to receive [`EGLImages`] for EGL-based [`WlBuffer`]s. /// -/// Can be created by using `EGLGraphicsBackend::bind_wl_display`. +/// Can be created by using [`EGLGraphicsBackend::bind_wl_display`]. #[cfg(feature = "native_lib")] pub struct EGLDisplay { egl: Weak, @@ -357,10 +357,10 @@ impl EGLDisplay { } } - /// Try to receive `EGLImages` from a given `WlBuffer`. + /// Try to receive [`EGLImages`] from a given [`WlBuffer`]. /// - /// In case the buffer is not managed by EGL (but e.g. the `wayland::shm` module) - /// a `BufferAccessError::NotManaged(WlBuffer)` is returned with the original buffer + /// In case the buffer is not managed by EGL (but e.g. the [`wayland::shm` module](::wayland::shm)) + /// a [`BufferAccessError::NotManaged`](::backend::egl::BufferAccessError::NotManaged) is returned with the original buffer /// to render it another way. pub fn egl_buffer_contents( &self, diff --git a/src/backend/egl/native.rs b/src/backend/egl/native.rs index 1edc445..9d797a9 100644 --- a/src/backend/egl/native.rs +++ b/src/backend/egl/native.rs @@ -18,11 +18,11 @@ pub trait Backend { /// Surface type created by this backend type Surface: NativeSurface; - /// Return an `EGLDisplay` based on this backend + /// Return an [`EGLDisplay`](ffi::egl::types::EGLDisplay) based on this backend /// /// # Unsafety /// - /// The returned `EGLDisplay` needs to be a valid pointer for EGL, + /// The returned [`EGLDisplay`](ffi::egl::types::EGLDisplay) needs to be a valid pointer for EGL, /// but there is no way to test that. unsafe fn get_display bool>( display: ffi::NativeDisplayType, @@ -91,18 +91,18 @@ impl Backend for X11 { } } -/// Trait for types returning Surfaces which can be used to initialize `EGLSurface`s +/// Trait for types returning Surfaces which can be used to initialize [`EGLSurface`](super::EGLSurface)s /// /// ## Unsafety /// -/// The returned `NativeDisplayType` must be valid for EGL and there is no way to test that. +/// The returned [`NativeDisplayType`](super::ffi::NativeDisplayType) must be valid for EGL and there is no way to test that. pub unsafe trait NativeDisplay { /// Arguments used to surface creation. type Arguments; /// Error type thrown by the surface creation in case of failure. type Error: ::std::error::Error + Send + 'static; - /// Because one type might implement multiple `Backend`s this function must be called to check - /// if the expected `Backend` is used at runtime. + /// Because one type might implement multiple [`Backend`]s this function must be called to check + /// if the expected [`Backend`] is used at runtime. fn is_backend(&self) -> bool; /// Return a raw pointer EGL will accept for context creation. fn ptr(&self) -> Result; @@ -163,7 +163,8 @@ unsafe impl NativeDisplay for WinitWindow { /// /// ## Unsafety /// -/// The returned `NativeWindowType` must be valid for EGL and there is no way to test that. +/// The returned [`NativeWindowType`](ffi::NativeWindowType) must be valid for EGL +/// and there is no way to test that. pub unsafe trait NativeSurface { /// Return a raw pointer egl will accept for surface creation. fn ptr(&self) -> ffi::NativeWindowType; @@ -187,7 +188,8 @@ pub unsafe trait NativeSurface { true } - /// Adds additional semantics when calling EGLSurface::swap_buffers + /// Adds additional semantics when calling + /// [EGLSurface::swap_buffers](::backend::egl::surface::EGLSurface::swap_buffers) /// /// Only implement if required by the backend. fn swap_buffers(&self) -> ::std::result::Result<(), SwapBuffersError> { diff --git a/src/backend/graphics/cursor.rs b/src/backend/graphics/cursor.rs index 7140bd5..7be3bc0 100644 --- a/src/backend/graphics/cursor.rs +++ b/src/backend/graphics/cursor.rs @@ -1,4 +1,9 @@ -/// Functions to render cursors on any graphics backend independently from it's rendering techique. +/// Functions to render cursors on graphics backend independently from it's rendering techique. +/// +/// In the most cases this will be the fastest available implementation utilizing hardware composing +/// where possible. This may however be quite restrictive in terms of supported formats. +/// +/// For those reasons you may always choose to render your cursor(s) (partially) in software instead. pub trait CursorBackend<'a> { /// Format representing the image drawn for the cursor. type CursorFormat: 'a; @@ -19,7 +24,7 @@ pub trait CursorBackend<'a> { /// fn set_cursor_position(&self, x: u32, y: u32) -> Result<(), Self::Error>; - /// Set the cursor drawn on the `CursorBackend`. + /// Set the cursor drawn on the [`CursorBackend`]. /// /// The format is entirely dictated by the concrete implementation and might range /// from raw image buffers over a fixed list of possible cursor types to simply the diff --git a/src/backend/graphics/gl.rs b/src/backend/graphics/gl.rs index b50e4ba..8f9d714 100644 --- a/src/backend/graphics/gl.rs +++ b/src/backend/graphics/gl.rs @@ -1,4 +1,4 @@ -//! Gl rendering types +//! OpenGL rendering types use nix::libc::c_void; @@ -45,11 +45,11 @@ pub trait GLGraphicsBackend { fn get_pixel_format(&self) -> PixelFormat; } -/// Loads a Raw GLES Interface for a given `GLGraphicsBackend` +/// Loads a Raw GLES Interface for a given [`GLGraphicsBackend`] /// -/// This remains valid as long as the underlying `GLGraphicsBackend` is alive +/// This remains valid as long as the underlying [`GLGraphicsBackend`] is alive /// and may only be used in combination with the backend. Using this with any -/// other gl context *may* cause undefined behavior. +/// other gl context or after the backend was dropped *may* cause undefined behavior. pub fn load_raw_gl(backend: &B) -> Gles2 { Gles2::load_with(|s| unsafe { backend.get_proc_address(s) as *const _ }) } diff --git a/src/backend/graphics/glium.rs b/src/backend/graphics/glium.rs index ab83d86..d146a28 100644 --- a/src/backend/graphics/glium.rs +++ b/src/backend/graphics/glium.rs @@ -45,10 +45,10 @@ impl GliumGraphicsBackend { /// Start drawing on the backbuffer. /// - /// This function returns a `Frame`, which can be used to draw on it. When the `Frame` is - /// destroyed, the buffers are swapped. + /// This function returns a [`Frame`], which can be used to draw on it. + /// When the [`Frame`] is destroyed, the buffers are swapped. /// - /// Note that destroying a `Frame` is immediate, even if vsync is enabled. + /// Note that destroying a [`Frame`] is immediate, even if vsync is enabled. #[inline] pub fn draw(&self) -> Frame { Frame::new(self.context.clone(), self.backend.get_framebuffer_dimensions()) @@ -56,7 +56,7 @@ impl GliumGraphicsBackend { /// Borrow the underlying backend. /// - /// This follows the same semantics as `std::cell:RefCell`. + /// This follows the same semantics as [`std::cell::RefCell`](RefCell::borrow). /// Multiple read-only borrows are possible. Borrowing the /// backend while there is a mutable reference will panic. pub fn borrow(&self) -> Ref { @@ -65,7 +65,7 @@ impl GliumGraphicsBackend { /// Borrow the underlying backend mutably. /// - /// This follows the same semantics as `std::cell:RefCell`. + /// This follows the same semantics as [`std::cell::RefCell`](RefCell::borrow_mut). /// Holding any other borrow while trying to borrow the backend /// mutably will panic. Note that Glium will borrow the backend /// (not mutably) during rendering. diff --git a/src/backend/input.rs b/src/backend/input.rs index 3c7063f..4db03de 100644 --- a/src/backend/input.rs +++ b/src/backend/input.rs @@ -10,8 +10,8 @@ use std::{error::Error, string::ToString}; /// separated users, all with their own focus, input and cursor available. /// /// Seats referring to the same internal id will always be equal and result in the same -/// hash, but capabilities of cloned and copied `Seat`s will not be updated by smithay. -/// Always refer to the `Seat` given by a callback for up-to-date information. You may +/// hash, but capabilities of cloned and copied [`Seat`]s will not be updated by smithay. +/// Always refer to the [`Seat`] given by a callback for up-to-date information. You may /// use this to calculate the differences since the last callback. #[derive(Debug, Clone, Eq)] pub struct Seat { @@ -33,12 +33,12 @@ impl Seat { &mut self.capabilities } - /// Get the currently capabilities of this `Seat` + /// Get the currently capabilities of this [`Seat`] pub fn capabilities(&self) -> &SeatCapabilities { &self.capabilities } - /// Get the name of this `Seat` + /// Get the name of this [`Seat`] pub fn name(&self) -> &str { &*self.name } @@ -59,14 +59,14 @@ impl ::std::hash::Hash for Seat { } } -/// Describes capabilities a `Seat` has. +/// Describes capabilities a [`Seat`] has. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct SeatCapabilities { - /// `Seat` has a pointer + /// [`Seat`] has a pointer pub pointer: bool, - /// `Seat` has a keyboard + /// [`Seat`] has a keyboard pub keyboard: bool, - /// `Seat` has a touchscreen + /// [`Seat`] has a touchscreen pub touch: bool, } @@ -81,10 +81,10 @@ pub trait Event { fn time(&self) -> u32; } -/// Used to mark events never emitted by an `InputBackend` implementation. +/// Used to mark events never emitted by an [`InputBackend`] implementation. /// -/// Implements all event types and can be used in place for any `Event` type, -/// that is not used by an `InputBackend` implementation. Initialization is not +/// Implements all event types and can be used in place for any [`Event`] type, +/// that is not used by an [`InputBackend`] implementation. Initialization is not /// possible, making accidental use impossible and enabling a lot of possible /// compiler optimizations. pub enum UnusedEvent {} @@ -110,7 +110,7 @@ pub trait KeyboardKeyEvent: Event { fn key_code(&self) -> u32; /// State of the key fn state(&self) -> KeyState; - /// Total number of keys pressed on all devices on the associated `Seat` + /// Total number of keys pressed on all devices on the associated [`Seat`] fn count(&self) -> u32; } @@ -190,7 +190,7 @@ pub enum AxisSource { /// cursor movement, i.e. a scroll value of 1 represents the equivalent relative /// motion of 1. Finger, - /// Continuous scrolling device. Almost identical to `Finger` + /// Continuous scrolling device. Almost identical to [`Finger`](AxisSource::Finger) /// /// No terminating event is guaranteed (though it may happen). /// @@ -212,14 +212,14 @@ pub enum AxisSource { /// Trait for pointer events generated by scrolling on an axis. pub trait PointerAxisEvent: Event { - /// Amount of scrolling in pixels on the given `Axis`. + /// Amount of scrolling in pixels on the given [`Axis`]. /// - /// Guaranteed to be `Some` when source returns either `AxisSource::Finger` or `AxisSource::Continuous`. + /// Guaranteed to be `Some` when source returns either [`AxisSource::Finger`] or [`AxisSource::Continuous`]. fn amount(&self, axis: &Axis) -> Option; - /// Amount of scrolling in discrete steps on the given `Axis`. + /// Amount of scrolling in discrete steps on the given [`Axis`]. /// - /// Guaranteed to be `Some` when source returns either `AxisSource::Wheel` or `AxisSource::WheelTilt`. + /// Guaranteed to be `Some` when source returns either [`AxisSource::Wheel`] or [`AxisSource::WheelTilt`]. fn amount_discrete(&self, axis: &Axis) -> Option; /// Source of the scroll event. @@ -336,7 +336,7 @@ impl TouchSlot { /// Trait for touch events starting at a given position. pub trait TouchDownEvent: Event { - /// `TouchSlot`, if the device has multi-touch capabilities + /// [`TouchSlot`], if the device has multi-touch capabilities fn slot(&self) -> Option; /// Touch position in the device's native coordinate space @@ -398,7 +398,7 @@ impl TouchDownEvent for UnusedEvent { /// Trait for touch events regarding movement on the screen pub trait TouchMotionEvent: Event { - /// `TouchSlot`, if the device has multi-touch capabilities + /// [`TouchSlot`], if the device has multi-touch capabilities fn slot(&self) -> Option; /// Touch position in the device's native coordinate space @@ -460,7 +460,7 @@ impl TouchMotionEvent for UnusedEvent { /// Trait for touch events finishing. pub trait TouchUpEvent: Event { - /// `TouchSlot`, if the device has multi-touch capabilities + /// [`TouchSlot`], if the device has multi-touch capabilities fn slot(&self) -> Option; } @@ -472,7 +472,7 @@ impl TouchUpEvent for UnusedEvent { /// Trait for touch events cancelling the chain pub trait TouchCancelEvent: Event { - /// `TouchSlot`, if the device has multi-touch capabilities + /// [`TouchSlot`], if the device has multi-touch capabilities fn slot(&self) -> Option; } @@ -518,7 +518,7 @@ pub trait InputBackend: Sized { /// Type representing touch frame events type TouchFrameEvent: TouchFrameEvent; - /// Sets a new handler for this `InputBackend` + /// Sets a new handler for this [`InputBackend`] fn set_handler + 'static>(&mut self, handler: H); /// Get a reference to the currently set handler, if any fn get_handler(&mut self) -> Option<&mut InputHandler>; @@ -528,17 +528,17 @@ pub trait InputBackend: Sized { /// Get current `InputConfig` fn input_config(&mut self) -> &mut Self::InputConfig; - /// Processes new events of the underlying backend and drives the `InputHandler`. + /// Processes new events of the underlying backend and drives the [`InputHandler`]. fn dispatch_new_events(&mut self) -> Result<(), Self::EventError>; } -/// Implement to receive input events from any `InputBackend`. +/// Implement to receive input events from any [`InputBackend`]. pub trait InputHandler { - /// Called when a new `Seat` has been created + /// Called when a new [`Seat`] has been created fn on_seat_created(&mut self, seat: &Seat); - /// Called when an existing `Seat` has been destroyed. + /// Called when an existing [`Seat`] has been destroyed. fn on_seat_destroyed(&mut self, seat: &Seat); - /// Called when a `Seat`'s properties have changed. + /// Called when a [`Seat`]'s properties have changed. /// /// ## Note: /// @@ -549,7 +549,7 @@ pub trait InputHandler { /// /// # Arguments /// - /// - `seat` - The `Seat` the event belongs to + /// - `seat` - The [`Seat`] the event belongs to /// - `event` - The keyboard event /// fn on_keyboard_key(&mut self, seat: &Seat, event: B::KeyboardKeyEvent); @@ -558,28 +558,28 @@ pub trait InputHandler { /// /// # Arguments /// - /// - `seat` - The `Seat` the event belongs to + /// - `seat` - The [`Seat`] the event belongs to /// - `event` - The pointer movement event fn on_pointer_move(&mut self, seat: &Seat, event: B::PointerMotionEvent); /// Called when a new pointer absolute movement event was received. /// /// # Arguments /// - /// - `seat` - The `Seat` the event belongs to + /// - `seat` - The [`Seat`] the event belongs to /// - `event` - The pointer absolute movement event fn on_pointer_move_absolute(&mut self, seat: &Seat, event: B::PointerMotionAbsoluteEvent); /// Called when a new pointer button event was received. /// /// # Arguments /// - /// - `seat` - The `Seat` the event belongs to + /// - `seat` - The [`Seat`] the event belongs to /// - `event` - The pointer button event fn on_pointer_button(&mut self, seat: &Seat, event: B::PointerButtonEvent); /// Called when a new pointer scroll event was received. /// /// # Arguments /// - /// - `seat` - The `Seat` the event belongs to + /// - `seat` - The [`Seat`] the event belongs to /// - `event` - A upward counting variable useful for event ordering. Makes no guarantees about actual time passed between events. fn on_pointer_axis(&mut self, seat: &Seat, event: B::PointerAxisEvent); @@ -587,35 +587,35 @@ pub trait InputHandler { /// /// # Arguments /// - /// - `seat` - The `Seat` the event belongs to + /// - `seat` - The [`Seat`] the event belongs to /// - `event` - The touch down event fn on_touch_down(&mut self, seat: &Seat, event: B::TouchDownEvent); /// Called when a new touch motion event was received. /// /// # Arguments /// - /// - `seat` - The `Seat` the event belongs to + /// - `seat` - The [`Seat`] the event belongs to /// - `event` - The touch motion event. fn on_touch_motion(&mut self, seat: &Seat, event: B::TouchMotionEvent); /// Called when a new touch up event was received. /// /// # Arguments /// - /// - `seat` - The `Seat` the event belongs to + /// - `seat` - The [`Seat`] the event belongs to /// - `event` - The touch up event. fn on_touch_up(&mut self, seat: &Seat, event: B::TouchUpEvent); /// Called when a new touch cancel event was received. /// /// # Arguments /// - /// - `seat` - The `Seat` the event belongs to + /// - `seat` - The [`Seat`] the event belongs to /// - `event` - The touch cancel event. fn on_touch_cancel(&mut self, seat: &Seat, event: B::TouchCancelEvent); /// Called when a new touch frame event was received. /// /// # Arguments /// - /// - `seat` - The `Seat` the event belongs to + /// - `seat` - The [`Seat`] the event belongs to /// - `event` - The touch frame event. fn on_touch_frame(&mut self, seat: &Seat, event: B::TouchFrameEvent); diff --git a/src/backend/libinput.rs b/src/backend/libinput.rs index d700b5a..dbeca0a 100644 --- a/src/backend/libinput.rs +++ b/src/backend/libinput.rs @@ -1,8 +1,8 @@ //! Implementation of input backend trait for types provided by `libinput` +use backend::input::{self as backend, Axis, InputBackend}; #[cfg(feature = "backend_session")] use backend::session::{AsErrno, Session, SessionObserver}; -use backend::{input as backend, input::Axis}; use input as libinput; use input::event; @@ -27,7 +27,7 @@ use wayland_server::calloop::{ #[cfg(all(any(target_os = "linux", target_os = "android"), feature = "backend_session"))] const INPUT_MAJOR: u32 = 13; -/// Libinput based `InputBackend`. +/// Libinput based [`InputBackend`]. /// /// Tracks input of all devices given manually or via a udev seat to a provided libinput /// context. @@ -40,8 +40,8 @@ pub struct LibinputInputBackend { } impl LibinputInputBackend { - /// Initialize a new `LibinputInputBackend` from a given already initialized libinput - /// context. + /// Initialize a new [`LibinputInputBackend`] from a given already initialized + /// [libinput context](libinput::Libinput). pub fn new(context: libinput::Libinput, logger: L) -> Self where L: Into>, @@ -248,7 +248,7 @@ impl backend::Event for event::touch::TouchFrameEvent { impl backend::TouchFrameEvent for event::touch::TouchFrameEvent {} -impl backend::InputBackend for LibinputInputBackend { +impl InputBackend for LibinputInputBackend { type InputConfig = [libinput::Device]; type EventError = IoError; @@ -565,8 +565,8 @@ impl SessionObserver for libinput::Libinput { } } -/// Wrapper for types implementing the `Session` trait to provide -/// a `LibinputInterface` implementation. +/// Wrapper for types implementing the [`Session`] trait to provide +/// a [`libinput::LibinputInterface`] implementation. #[cfg(feature = "backend_session")] pub struct LibinputSessionInterface(S); @@ -597,10 +597,10 @@ impl AsRawFd for LibinputInputBackend { } } -/// Binds a `LibinputInputBackend` to a given `EventLoop`. +/// Binds a [`LibinputInputBackend`] to a given [`LoopHandle`]. /// /// Automatically feeds the backend with incoming events without any manual calls to -/// `dispatch_new_events`. Should be used to achieve the smallest possible latency. +/// [`dispatch_new_events`](InputBackend::dispatch_new_events). Should be used to achieve the smallest possible latency. pub fn libinput_bind( backend: LibinputInputBackend, handle: LoopHandle, diff --git a/src/backend/session/auto.rs b/src/backend/session/auto.rs index b192076..3fe1aed 100644 --- a/src/backend/session/auto.rs +++ b/src/backend/session/auto.rs @@ -1,31 +1,32 @@ -//! Implementation of the `Session` trait through various implementations +//! Implementation of the [`Session`] trait through various implementations //! automatically choosing the best available interface. //! //! ## How to use it //! //! ### Initialization //! -//! To initialize a session just call `AutoSession::new`. A new session will be opened, if the -//! any available interface is successful and will be closed once the `AutoSessionNotifier` is dropped. +//! To initialize a session just call [`AutoSession::new`](::backend::session::auto::AutoSession::new). +//! A new session will be opened, if the any available interface is successful and will be closed once the +//! [`AutoSessionNotifier`](::backend::session::auto::AutoSessionNotifier) is dropped. //! //! ### Usage of the session //! -//! The session may be used to open devices manually through the `Session` interface +//! The session may be used to open devices manually through the [`Session`] interface //! or be passed to other objects that need it to open devices themselves. -//! The `AutoSession` is clonable and may be passed to multiple devices easily. +//! The [`AutoSession`](::backend::session::auto::AutoSession) is clonable +//! and may be passed to multiple devices easily. //! -//! Examples for those are e.g. the `LibinputInputBackend` (its context might be initialized through a -//! `Session` via the `LibinputSessionInterface`) or the `UdevBackend`. +//! Examples for those are e.g. the [`LibinputInputBackend`](::backend::libinput::LibinputInputBackend) +//! (its context might be initialized through a [`Session`] via the [`LibinputSessionInterface`](::backend::libinput::LibinputSessionInterface)). //! //! ### Usage of the session notifier //! //! The notifier might be used to pause device access, when the session gets paused (e.g. by -//! switching the tty via `AutoSession::change_vt`) and to automatically enable it again, -//! when the session becomes active again. +//! switching the tty via [`AutoSession::change_vt`](::backend::session::Session::change_vt)) +//! and to automatically enable it again, when the session becomes active again. //! //! It is crucial to avoid errors during that state. Examples for object that might be registered -//! for notifications are the `Libinput` context, the `UdevBackend` or a `DrmDevice` (handled -//! automatically by the `UdevBackend`, if not done manually). +//! for notifications are the [`Libinput`](input::Libinput) context or the [`Device`](::backend::drm::Device). #[cfg(feature = "backend_session_logind")] use super::logind::{self, logind_session_bind, BoundLogindSession, LogindSession, LogindSessionNotifier}; @@ -38,7 +39,7 @@ use std::{cell::RefCell, io::Error as IoError, os::unix::io::RawFd, path::Path, use wayland_server::calloop::LoopHandle; -/// `Session` using the best available interface +/// [`Session`] using the best available interface #[derive(Clone)] pub enum AutoSession { /// Logind session @@ -48,7 +49,7 @@ pub enum AutoSession { Direct(Rc>), } -/// `SessionNotifier` using the best available interface +/// [`SessionNotifier`] using the best available interface pub enum AutoSessionNotifier { /// Logind session notifier #[cfg(feature = "backend_session_logind")] @@ -57,11 +58,11 @@ pub enum AutoSessionNotifier { Direct(DirectSessionNotifier), } -/// Bound session that is driven by the `calloop::EventLoop`. +/// Bound session that is driven by a [`EventLoop`](wayland_server::calloop::EventLoop). /// -/// See `auto_session_bind` for details. +/// See [`auto_session_bind`] for details. /// -/// Dropping this object will close the session just like the `AutoSessionNotifier`. +/// Dropping this object will close the session just like the [`AutoSessionNotifier`]. pub enum BoundAutoSession { /// Bound logind session #[cfg(feature = "backend_session_logind")] @@ -70,7 +71,7 @@ pub enum BoundAutoSession { Direct(BoundDirectSession), } -/// Id's used by the `AutoSessionNotifier` internally. +/// Id's used by the [`AutoSessionNotifier`] internally. #[derive(Debug, PartialEq, Eq, Clone, Copy)] pub struct AutoId(AutoIdInternal); #[derive(Debug, PartialEq, Eq, Clone, Copy)] @@ -138,11 +139,11 @@ impl AutoSession { } } -/// Bind an `AutoSessionNotifier` to an `EventLoop`. +/// Bind an [`AutoSessionNotifier`] to an [`EventLoop`](wayland_server::calloop::EventLoop). /// -/// Allows the `AutoSessionNotifier` to listen for incoming signals signalling the session state. -/// If you don't use this function `AutoSessionNotifier` will not correctly tell you the -/// session state and call its `SessionObservers`. +/// Allows the [`AutoSessionNotifier`] to listen for incoming signals signalling the session state. +/// If you don't use this function [`AutoSessionNotifier`] will not correctly tell you the +/// session state and call its [`SessionObserver`]s. pub fn auto_session_bind( notifier: AutoSessionNotifier, handle: &LoopHandle, @@ -232,7 +233,7 @@ impl SessionNotifier for AutoSessionNotifier { } impl BoundAutoSession { - /// Unbind the session from the `EventLoop` again + /// Unbind the session from the [`EventLoop`](wayland_server::calloop::EventLoop) again pub fn unbind(self) -> AutoSessionNotifier { match self { #[cfg(feature = "backend_session_logind")] @@ -242,15 +243,22 @@ impl BoundAutoSession { } } -error_chain! { - links { - Logind(logind::Error, logind::ErrorKind) #[cfg(feature = "backend_session_logind")] #[doc = "Underlying logind session error"]; - } +/// Errors related to auto sessions +pub mod errors { + #[cfg(feature = "backend_session_logind")] + use super::logind::errors as logind; - foreign_links { - Direct(::nix::Error) #[doc = "Underlying direct tty session error"]; + error_chain! { + links { + Logind(logind::Error, logind::ErrorKind) #[cfg(feature = "backend_session_logind")] #[doc = "Underlying logind session error"]; + } + + foreign_links { + Direct(::nix::Error) #[doc = "Underlying direct tty session error"]; + } } } +use self::errors::*; impl AsErrno for Error { fn as_errno(&self) -> Option { diff --git a/src/backend/session/dbus/logind.rs b/src/backend/session/dbus/logind.rs index 9450bc6..6a02bef 100644 --- a/src/backend/session/dbus/logind.rs +++ b/src/backend/session/dbus/logind.rs @@ -1,5 +1,5 @@ //! -//! Implementation of the `Session` trait through the logind dbus interface. +//! Implementation of the [`Session`](::backend::session::Session) trait through the logind dbus interface. //! //! This requires systemd and dbus to be available and started on the system. //! @@ -7,28 +7,29 @@ //! //! ### Initialization //! -//! To initialize a session just call `LogindSession::new`. A new session will be opened, if the -//! call is successful and will be closed once the `LogindSessionNotifier` is dropped. +//! To initialize a session just call [`LogindSession::new`](::backend::session::dbus::logind::LogindSession::new). +//! A new session will be opened, if the call is successful and will be closed once the +//! [`LogindSessionNotifier`](::backend::session::dbus::logind::LogindSessionNotifier) is dropped. //! //! ### Usage of the session //! -//! The session may be used to open devices manually through the `Session` interface +//! The session may be used to open devices manually through the [`Session`](::backend::session::Session) interface //! or be passed to other objects that need it to open devices themselves. -//! The `LogindSession` is clonable and may be passed to multiple devices easily. +//! The [`LogindSession`](::backend::session::dbus::logind::LogindSession) is clonable +//! and may be passed to multiple devices easily. //! -//! Examples for those are e.g. the `LibinputInputBackend` (its context might be initialized through a -//! `Session` via the `LibinputSessionInterface`) or the `UdevBackend`. +//! Examples for those are e.g. the [`LibinputInputBackend`](::backend::libinput::LibinputInputBackend) +//! (its context might be initialized through a [`Session`](::backend::session::Session) via the +//! [`LibinputSessionInterface`](::backend::libinput::LibinputSessionInterface)). //! //! ### Usage of the session notifier //! //! The notifier might be used to pause device access, when the session gets paused (e.g. by -//! switching the tty via `LogindSession::change_vt`) and to automatically enable it again, -//! when the session becomes active again. +//! switching the tty via [`LogindSession::change_vt`](::backend::session::Session::change_vt)) +//! and to automatically enable it again, when the session becomes active again. //! //! It is crucial to avoid errors during that state. Examples for object that might be registered -//! for notifications are the `Libinput` context, the `UdevBackend` or a `DrmDevice` (handled -//! automatically by the `UdevBackend`, if not done manually). -//! ``` +//! for notifications are the [`Libinput`](input::Libinput) context or the [`Device`](::backend::drm::Device). use backend::session::{AsErrno, Session, SessionNotifier, SessionObserver}; use dbus::{ @@ -64,14 +65,14 @@ struct LogindSessionImpl { logger: ::slog::Logger, } -/// `Session` via the logind dbus interface +/// [`Session`] via the logind dbus interface #[derive(Clone)] pub struct LogindSession { internal: Weak, seat: String, } -/// `SessionNotifier` via the logind dbus interface +/// [`SessionNotifier`] via the logind dbus interface #[derive(Clone)] pub struct LogindSessionNotifier { internal: Rc, @@ -401,7 +402,7 @@ impl Session for LogindSession { } } -/// Ids of registered `SessionObserver`s of the `LogindSessionNotifier` +/// Ids of registered [`SessionObserver`]s of the [`LogindSessionNotifier`] #[derive(Debug, PartialEq, Eq, Clone, Copy)] pub struct Id(usize); @@ -417,22 +418,22 @@ impl SessionNotifier for LogindSessionNotifier { } } -/// Bound logind session that is driven by the `wayland_server::EventLoop`. +/// Bound logind session that is driven by the [`EventLoop`](wayland_server::calloop::EventLoop). /// -/// See `logind_session_bind` for details. +/// See [`logind_session_bind`] for details. /// -/// Dropping this object will close the logind session just like the `LogindSessionNotifier`. +/// Dropping this object will close the logind session just like the [`LogindSessionNotifier`]. pub struct BoundLogindSession { notifier: LogindSessionNotifier, _watches: Vec, sources: Vec>>, } -/// Bind a `LogindSessionNotifier` to an `EventLoop`. +/// Bind a [`LogindSessionNotifier`] to an [`EventLoop`](wayland_server::calloop::EventLoop). /// -/// Allows the `LogindSessionNotifier` to listen for incoming signals signalling the session state. -/// If you don't use this function `LogindSessionNotifier` will not correctly tell you the logind -/// session state and call it's `SessionObservers`. +/// Allows the [`LogindSessionNotifier`] to listen for incoming signals signalling the session state. +/// If you don't use this function [`LogindSessionNotifier`] will not correctly tell you the logind +/// session state and call it's [`SessionObserver`]s. pub fn logind_session_bind( notifier: LogindSessionNotifier, handle: &LoopHandle, @@ -471,7 +472,7 @@ pub fn logind_session_bind( } impl BoundLogindSession { - /// Unbind the logind session from the `EventLoop` + /// Unbind the logind session from the [`EventLoop`](wayland_server::calloop::EventLoop) pub fn unbind(self) -> LogindSessionNotifier { for source in self.sources { source.remove(); @@ -518,62 +519,68 @@ impl LogindSessionNotifier { } } -error_chain! { - errors { - #[doc = "Failed to connect to dbus system socket"] - FailedDbusConnection { - description("Failed to connect to dbus system socket"), - } +/// Errors related to logind sessions +pub mod errors { + use dbus::{BusName, Interface, Member, Path as DbusPath}; - #[doc = "Failed to get session from logind"] - FailedToGetSession { - description("Failed to get session from logind") - } + error_chain! { + errors { + #[doc = "Failed to connect to dbus system socket"] + FailedDbusConnection { + description("Failed to connect to dbus system socket"), + } - #[doc = "Failed to get seat from logind"] - FailedToGetSeat { - description("Failed to get seat from logind") - } + #[doc = "Failed to get session from logind"] + FailedToGetSession { + description("Failed to get session from logind") + } - #[doc = "Failed to get vt from logind"] - FailedToGetVT { - description("Failed to get vt from logind") - } + #[doc = "Failed to get seat from logind"] + FailedToGetSeat { + description("Failed to get seat from logind") + } - #[doc = "Failed to call dbus method"] - FailedToSendDbusCall(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) { - description("Failed to call dbus method") - display("Failed to call dbus method for service: {:?}, path: {:?}, interface: {:?}, member: {:?}", bus, path, interface, member), - } + #[doc = "Failed to get vt from logind"] + FailedToGetVT { + description("Failed to get vt from logind") + } - #[doc = "Dbus method call failed"] - DbusCallFailed(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) { - description("Dbus method call failed") - display("Dbus message call failed for service: {:?}, path: {:?}, interface: {:?}, member: {:?}", bus, path, interface, member), - } + #[doc = "Failed to call dbus method"] + FailedToSendDbusCall(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) { + description("Failed to call dbus method") + display("Failed to call dbus method for service: {:?}, path: {:?}, interface: {:?}, member: {:?}", bus, path, interface, member), + } - #[doc = "Dbus method return had unexpected format"] - UnexpectedMethodReturn { - description("Dbus method return returned unexpected format") - } + #[doc = "Dbus method call failed"] + DbusCallFailed(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) { + description("Dbus method call failed") + display("Dbus message call failed for service: {:?}, path: {:?}, interface: {:?}, member: {:?}", bus, path, interface, member), + } - #[doc = "Failed to setup dbus match rule"] - DbusMatchFailed(rule: String) { - description("Failed to setup dbus match rule"), - display("Failed to setup dbus match rule {}", rule), - } + #[doc = "Dbus method return had unexpected format"] + UnexpectedMethodReturn { + description("Dbus method return returned unexpected format") + } - #[doc = "Failed to stat device"] - FailedToStatDevice { - description("Failed to stat device") - } + #[doc = "Failed to setup dbus match rule"] + DbusMatchFailed(rule: String) { + description("Failed to setup dbus match rule"), + display("Failed to setup dbus match rule {}", rule), + } - #[doc = "Session is already closed"] - SessionLost { - description("Session is already closed") + #[doc = "Failed to stat device"] + FailedToStatDevice { + description("Failed to stat device") + } + + #[doc = "Session is already closed"] + SessionLost { + description("Session is already closed") + } } } } +use self::errors::*; impl AsErrno for Error { fn as_errno(&self) -> Option { diff --git a/src/backend/session/direct.rs b/src/backend/session/direct.rs index cdb60d6..00bb98d 100644 --- a/src/backend/session/direct.rs +++ b/src/backend/session/direct.rs @@ -1,5 +1,5 @@ //! -//! Implementation of the `Session` trait through the legacy vt kernel interface. +//! Implementation of the [`Session`](Session) trait through the legacy vt kernel interface. //! //! This requires write permissions for the given tty device and any devices opened through this //! interface. This means it will almost certainly require root permissions and not allow to run @@ -26,24 +26,23 @@ //! //! ### Usage of the session //! -//! The session may be used to open devices manually through the `Session` interface +//! The session may be used to open devices manually through the [`Session`] interface //! or be passed to other objects that need it to open devices themselves. //! -//! Examples for those are e.g. the `LibinputInputBackend` (its context might be initialized through a -//! `Session` via the `LibinputSessionInterface`) or the `UdevBackend`. +//! Examples for those are e.g. the [`LibinputInputBackend`](::backend::libinput::LibinputInputBackend) +//! (its context might be initialized through a [`Session`] via the [`LibinputSessionInterface`](::backend::libinput::LibinputSessionInterface)). //! -//! In case you want to pass the same `Session` to multiple objects, `Session` is implement for +//! In case you want to pass the same [`Session`] to multiple objects, [`Session`] is implement for //! every `Rc>` or `Arc>`. //! //! ### Usage of the session notifier //! //! The notifier might be used to pause device access, when the session gets paused (e.g. by -//! switching the tty via `DirectSession::change_vt`) and to automatically enable it again, -//! when the session becomes active again. +//! switching the tty via [`DirectSession::change_vt`](::backend::session::Session::change_vt)) +//! and to automatically enable it again, when the session becomes active again. //! //! It is crucial to avoid errors during that state. Examples for object that might be registered -//! for notifications are the `Libinput` context, the `UdevBackend` or a `DrmDevice` (handled -//! automatically by the `UdevBackend`, if not done manually). +//! for notifications are the [`Libinput`](input::Libinput) context or the [`Device`](::backend::drm::Device). use super::{AsErrno, Session, SessionNotifier, SessionObserver}; use nix::{ @@ -150,7 +149,7 @@ fn is_tty_device(dev: dev_t, path: Option<&Path>) -> bool { } } -/// `Session` via the virtual terminal direct kernel interface +/// [`Session`] via the virtual terminal direct kernel interface pub struct DirectSession { tty: RawFd, active: Arc, @@ -159,7 +158,7 @@ pub struct DirectSession { logger: ::slog::Logger, } -/// `SessionNotifier` via the virtual terminal direct kernel interface +/// [`SessionNotifier`] via the virtual terminal direct kernel interface pub struct DirectSessionNotifier { tty: RawFd, active: Arc, @@ -253,7 +252,7 @@ impl DirectSession { // https://github.com/nix-rust/nix/issues/495 /* let signal = if tty::__libc_current_sigrtmin() > tty::__libc_current_sigrtmax() { - warn!(logger, "Not enough real-time signals available, falling back to USR1"); + warn!(logger, "Not enough real-time signals available, falling back to USR2"); nix::sys::signal::SIGUSR2 as i32 } else { tty::__libc_current_sigrtmin() @@ -345,7 +344,7 @@ impl Drop for DirectSession { } } -/// Ids of registered `SessionObserver`s of the `DirectSessionNotifier` +/// Ids of registered [`SessionObserver`]s of the [`DirectSessionNotifier`] #[derive(Debug, PartialEq, Eq, Clone, Copy)] pub struct Id(usize); @@ -391,16 +390,16 @@ impl DirectSessionNotifier { } } -/// Bound logind session that is driven by the `wayland_server::EventLoop`. +/// Bound logind session that is driven by the [`EventLoop`](wayland_server::calloop::EventLoop). /// -/// See `direct_session_bind` for details. +/// See [`direct_session_bind`] for details. pub struct BoundDirectSession { source: Source, notifier: Rc>, } impl BoundDirectSession { - /// Unbind the direct session from the `EventLoop` + /// Unbind the direct session from the [`EventLoop`](wayland_server::calloop::EventLoop) pub fn unbind(self) -> DirectSessionNotifier { let BoundDirectSession { source, notifier } = self; source.remove(); @@ -411,11 +410,11 @@ impl BoundDirectSession { } } -/// Bind a `DirectSessionNotifier` to an `EventLoop`. +/// Bind a [`DirectSessionNotifier`] to an [`EventLoop`](wayland_server::calloop::EventLoop). /// -/// Allows the `DirectSessionNotifier` to listen for incoming signals signalling the session state. -/// If you don't use this function `DirectSessionNotifier` will not correctly tell you the current -/// session state and call it's `SessionObservers`. +/// Allows the [`DirectSessionNotifier`] to listen for incoming signals signalling the session state. +/// If you don't use this function [`DirectSessionNotifier`] will not correctly tell you the current +/// session state and call it's [`SessionObserver`]s. pub fn direct_session_bind( notifier: DirectSessionNotifier, handle: &LoopHandle, @@ -442,59 +441,63 @@ pub fn direct_session_bind( Ok(BoundDirectSession { source, notifier }) } -error_chain! { - errors { - #[doc = "Failed to open tty"] - FailedToOpenTTY(path: String) { - description("Failed to open tty"), - display("Failed to open tty ({:?})", path), - } +/// Errors related to direct/tty sessions +pub mod errors { + error_chain! { + errors { + #[doc = "Failed to open tty"] + FailedToOpenTTY(path: String) { + description("Failed to open tty"), + display("Failed to open tty ({:?})", path), + } - #[doc = "Not running from a tty"] - NotRunningFromTTY { - description("Not running from a tty"), - } + #[doc = "Not running from a tty"] + NotRunningFromTTY { + description("Not running from a tty"), + } - #[doc = "tty is already in KB_GRAPHICS mode"] - TTYAlreadyInGraphicsMode { - description("The tty is already in KB_GRAPHICS mode"), - display("The tty is already in graphics mode, is already a compositor running?"), - } + #[doc = "tty is already in KB_GRAPHICS mode"] + TTYAlreadyInGraphicsMode { + description("The tty is already in KB_GRAPHICS mode"), + display("The tty is already in graphics mode, is already a compositor running?"), + } - #[doc = "Failed to activate open tty"] - FailedToActivateTTY(num: i32) { - description("Failed to activate open tty"), - display("Failed to activate open tty ({:?})", num), - } + #[doc = "Failed to activate open tty"] + FailedToActivateTTY(num: i32) { + description("Failed to activate open tty"), + display("Failed to activate open tty ({:?})", num), + } - #[doc = "Failed to wait for tty to become active"] - FailedToWaitForTTY(num: i32) { - description("Failed to wait for tty to become active"), - display("Failed to wait for tty ({:?}) to become active", num), - } + #[doc = "Failed to wait for tty to become active"] + FailedToWaitForTTY(num: i32) { + description("Failed to wait for tty to become active"), + display("Failed to wait for tty ({:?}) to become active", num), + } - #[doc = "Failed to save old tty state"] - FailedToSaveTTYState(num: i32) { - description("Failed to save old tty state"), - display("Failed to save old tty ({:?}) state", num), - } + #[doc = "Failed to save old tty state"] + FailedToSaveTTYState(num: i32) { + description("Failed to save old tty state"), + display("Failed to save old tty ({:?}) state", num), + } - #[doc = "Failed to set tty kb mode"] - FailedToSetTTYKbMode(num: i32) { - description("Failed to set tty kb mode to K_OFF"), - display("Failed to set tty ({:?}) kb mode to K_OFF", num), - } + #[doc = "Failed to set tty kb mode"] + FailedToSetTTYKbMode(num: i32) { + description("Failed to set tty kb mode to K_OFF"), + display("Failed to set tty ({:?}) kb mode to K_OFF", num), + } - #[doc = "Failed to set tty mode"] - FailedToSetTTYMode(num: i32) { - description("Failed to set tty mode to KD_GRAPHICS"), - display("Failed to set tty ({:?}) mode into graphics mode", num), - } + #[doc = "Failed to set tty mode"] + FailedToSetTTYMode(num: i32) { + description("Failed to set tty mode to KD_GRAPHICS"), + display("Failed to set tty ({:?}) mode into graphics mode", num), + } - #[doc = "Failed to set tty in process mode"] - FailedToTakeControlOfTTY(num: i32) { - description("Failed to set tty mode to VT_PROCESS"), - display("Failed to take control of tty ({:?})", num), + #[doc = "Failed to set tty in process mode"] + FailedToTakeControlOfTTY(num: i32) { + description("Failed to set tty mode to VT_PROCESS"), + display("Failed to take control of tty ({:?})", num), + } } } } +use self::errors::*; diff --git a/src/backend/session/mod.rs b/src/backend/session/mod.rs index 8967233..e266699 100644 --- a/src/backend/session/mod.rs +++ b/src/backend/session/mod.rs @@ -45,25 +45,26 @@ pub trait Session { /// Interface for registering for notifications for a given session. /// /// Part of the session API which allows to get notified, when the given session -/// gets paused or becomes active again. Any object implementing the `SessionObserver` trait -/// may be registered. +/// gets paused or becomes active again. Any object implementing the [`SessionObserver`] +/// trait may be registered. pub trait SessionNotifier { /// Id type of registered observers type Id: PartialEq + Eq; - /// Registers a given `SessionObserver`. + /// Registers a given [`SessionObserver`]. /// /// Returns an id of the inserted observer, can be used to remove it again. fn register(&mut self, signal: S) -> Self::Id; - /// Removes an observer by its given id from `SessionNotifier::register`. + /// Removes an observer by its given id from [`SessionNotifier::register`]. fn unregister(&mut self, signal: Self::Id); } -/// Trait describing the ability to return a `SessionObserver` related to Self. +/// Trait describing the ability to return a [`SessionObserver`] related to Self. /// -/// The returned `SessionObserver` is responsible to handle the `pause` and `activate` signals. +/// The returned [`SessionObserver`] is responsible to handle the [`pause`](SessionObserver::pause) +/// and [`activate`](SessionObserver::activate) signals. pub trait AsSessionObserver { - /// Create a `SessionObserver` linked to this object + /// Create a [`SessionObserver`] linked to this object fn observer(&mut self) -> S; } diff --git a/src/backend/session/multi.rs b/src/backend/session/multi.rs index 4cd3fb7..9054e5c 100644 --- a/src/backend/session/multi.rs +++ b/src/backend/session/multi.rs @@ -11,7 +11,7 @@ use super::{SessionNotifier, SessionObserver}; static ID_COUNTER: AtomicUsize = AtomicUsize::new(0); -/// Ids of registered `SessionObserver`s of the `DirectSessionNotifier` +/// Ids of registered [`SessionObserver`](SessionObserver)s #[derive(Debug, PartialEq, Eq, Clone, Copy, Hash)] pub struct Id(usize); @@ -52,8 +52,8 @@ impl SessionNotifier for MultiNotifier { } } -/// Create a pair of a linked [`SessionObserver`](../trait.SessionObserver.html) and a -/// [`SessionNotifier`](../trait.SessionNotifier.html). +/// Create a pair of a linked [`SessionObserver`] and a +/// [`SessionNotifier`](SessionNotifier). /// /// Observers added to the returned notifier are notified, /// when the returned observer is notified. diff --git a/src/backend/udev.rs b/src/backend/udev.rs index cc2f901..2501563 100644 --- a/src/backend/udev.rs +++ b/src/backend/udev.rs @@ -1,12 +1,12 @@ //! //! Provides `udev` related functionality for automated device scanning. //! -//! This module mainly provides the `UdevBackend`, which constantly monitors available DRM devices -//! and notifies a user supplied `UdevHandler` of any changes. +//! This module mainly provides the [`UdevBackend`](::backend::udev::UdevBackend), which constantly monitors available DRM devices +//! and notifies a user supplied [`UdevHandler`](::backend::udev::UdevHandler) of any changes. //! //! Additionally this contains some utility functions related to scanning. //! -//! See also `examples/udev.rs` for pure hardware backed example of a compositor utilizing this +//! See also `anvil/src/udev.rs` for pure hardware backed example of a compositor utilizing this //! backend. use nix::sys::stat::{dev_t, stat}; @@ -43,7 +43,7 @@ impl AsRawFd for UdevBackend { } impl UdevBackend { - /// Creates a new `UdevBackend` and adds it to the given `EventLoop`'s state. + /// Creates a new [`UdevBackend`] /// /// ## Arguments /// `context` - An initialized udev context @@ -97,9 +97,9 @@ impl Drop for UdevBackend { } } -/// Binds a `UdevBackend` to a given `EventLoop`. +/// Binds a [`UdevBackend`] to a given [`EventLoop`](wayland_server::calloop::EventLoop). /// -/// Allows the backend to receive kernel events and thus to drive the `UdevHandler`. +/// Allows the backend to receive kernel events and thus to drive the [`UdevHandler`]. /// No runtime functionality can be provided without using this function. pub fn udev_backend_bind( udev: UdevBackend, @@ -156,7 +156,7 @@ impl UdevBackend { } } -/// Handler for the `UdevBackend`, allows to open, close and update drm devices as they change during runtime. +/// Handler for the [`UdevBackend`], allows to open, close and update drm devices as they change during runtime. pub trait UdevHandler { /// Called when a new device is detected. fn device_added(&mut self, device: dev_t, path: PathBuf); @@ -166,16 +166,13 @@ pub trait UdevHandler { /// should scan again for connected monitors and mode switch accordingly. fn device_changed(&mut self, device: dev_t); /// Called when a device was removed. - /// - /// The corresponding `UdevRawFd` will never return a valid `RawFd` anymore - /// and its file descriptor will be closed once this function returns, - /// any open references/tokens to this device need to be released. fn device_removed(&mut self, device: dev_t); } /// Returns the path of the primary GPU device if any /// -/// Might be used for filtering in `UdevHandler::device_added` or for manual `DrmDevice` initialization +/// Might be used for filtering in [`UdevHandler::device_added`] or for manual +/// [`LegacyDrmDevice`](::backend::drm::legacy::LegacyDrmDevice) initialization. pub fn primary_gpu>(context: &Context, seat: S) -> UdevResult> { let mut enumerator = Enumerator::new(context)?; enumerator.match_subsystem("drm")?; @@ -205,7 +202,8 @@ pub fn primary_gpu>(context: &Context, seat: S) -> UdevResult>(context: &Context, seat: S) -> UdevResult> { let mut enumerator = Enumerator::new(context)?; enumerator.match_subsystem("drm")?; diff --git a/src/backend/winit.rs b/src/backend/winit.rs index 0b94085..2ad70b6 100644 --- a/src/backend/winit.rs +++ b/src/backend/winit.rs @@ -2,8 +2,8 @@ use backend::{ egl::{ - context::GlAttributes, error as egl_error, error::Result as EGLResult, native, EGLContext, - EGLDisplay, EGLGraphicsBackend, EGLSurface, + context::GlAttributes, error::Result as EGLResult, native, EGLContext, EGLDisplay, + EGLGraphicsBackend, EGLSurface, }, graphics::{gl::GLGraphicsBackend, CursorBackend, PixelFormat, SwapBuffersError}, input::{ @@ -16,7 +16,7 @@ use backend::{ use nix::libc::c_void; use std::{ cell::{Ref, RefCell}, - cmp, error, fmt, + cmp, fmt, rc::Rc, time::Instant, }; @@ -28,23 +28,29 @@ use winit::{ MouseScrollDelta, Touch, TouchPhase, Window as WinitWindow, WindowBuilder, WindowEvent, }; -error_chain! { - errors { - #[doc = "Failed to initialize a window"] - InitFailed { - description("Failed to initialize a window") +/// Errors thrown by the `winit` backends +pub mod errors { + use backend::egl::error as egl_error; + + error_chain! { + errors { + #[doc = "Failed to initialize a window"] + InitFailed { + description("Failed to initialize a window") + } + + #[doc = "Context creation is not supported on the current window system"] + NotSupported { + description("Context creation is not supported on the current window system.") + } } - #[doc = "Context creation is not supported on the current window system"] - NotSupported { - description("Context creation is not supported on the current window system.") + links { + EGL(egl_error::Error, egl_error::ErrorKind) #[doc = "EGL error"]; } } - - links { - EGL(egl_error::Error, egl_error::ErrorKind) #[doc = "EGL error"]; - } } +use self::errors::*; enum Window { Wayland { @@ -72,16 +78,17 @@ struct WindowSize { } /// Window with an active EGL Context created by `winit`. Implements the -/// `EGLGraphicsBackend` graphics backend trait +/// [`EGLGraphicsBackend`] and [`GLGraphicsBackend`] graphics backend trait pub struct WinitGraphicsBackend { window: Rc, size: Rc>, logger: ::slog::Logger, } -/// Abstracted event loop of a `winit` `Window` implementing the `InputBackend` trait +/// Abstracted event loop of a [`WinitWindow`] implementing the [`InputBackend`] trait /// -/// You need to call `dispatch_new_events` periodically to receive any events. +/// You need to call [`dispatch_new_events`](InputBackend::dispatch_new_events) +/// periodically to receive any events. pub struct WinitInputBackend { events_loop: EventsLoop, events_handler: Option>, @@ -95,9 +102,9 @@ pub struct WinitInputBackend { size: Rc>, } -/// Create a new `WinitGraphicsBackend`, which implements the `EGLGraphicsBackend` -/// graphics backend trait and a corresponding `WinitInputBackend`, which implements -/// the `InputBackend` trait +/// Create a new [`WinitGraphicsBackend`], which implements the [`EGLGraphicsBackend`] +/// and [`GLGraphicsBackend`] graphics backend trait and a corresponding [`WinitInputBackend`], +/// which implements the [`InputBackend`] trait pub fn init(logger: L) -> Result<(WinitGraphicsBackend, WinitInputBackend)> where L: Into>, @@ -111,9 +118,9 @@ where ) } -/// Create a new `WinitGraphicsBackend`, which implements the `EGLGraphicsBackend` -/// graphics backend trait, from a given `WindowBuilder` struct and a corresponding -/// `WinitInputBackend`, which implements the `InputBackend` trait +/// Create a new [`WinitGraphicsBackend`], which implements the [`EGLGraphicsBackend`] +/// and [`GLGraphicsBackend`] graphics backend trait, from a given [`WindowBuilder`] +/// struct and a corresponding [`WinitInputBackend`], which implements the [`InputBackend`] trait pub fn init_from_builder( builder: WindowBuilder, logger: L, @@ -133,10 +140,10 @@ where ) } -/// Create a new `WinitGraphicsBackend`, which implements the `EGLGraphicsBackend` -/// graphics backend trait, from a given `WindowBuilder` struct, as well as given -/// `GlAttributes` for further customization of the rendering pipeline and a -/// corresponding `WinitInputBackend`, which implements the `InputBackend` trait. +/// Create a new [`WinitGraphicsBackend`], which implements the [`EGLGraphicsBackend`] +/// and [`GLGraphicsBackend`] graphics backend trait, from a given [`WindowBuilder`] +/// struct, as well as given [`GlAttributes`] for further customization of the rendering pipeline and a +/// corresponding [`WinitInputBackend`], which implements the [`InputBackend`] trait. pub fn init_from_builder_with_gl_attr( builder: WindowBuilder, attributes: GlAttributes, @@ -208,7 +215,7 @@ where /// Handler trait to receive window-related events to provide a better *nested* experience. pub trait WinitEventsHandler { - /// The window was resized, can be used to adjust the associated `wayland::output::Output`s mode. + /// The window was resized, can be used to adjust the associated [`Output`](::wayland::output::Output)s mode. /// /// Here are provided the new size (in physical pixels) and the new scale factor provided by `winit`. fn resized(&mut self, size: (f64, f64), scale: f64); @@ -219,7 +226,7 @@ pub trait WinitEventsHandler { } impl WinitGraphicsBackend { - /// Get a reference to the internally used `winit::Window` + /// Get a reference to the internally used [`WinitWindow`] pub fn winit_window(&self) -> Ref { self.window.window() } @@ -314,16 +321,16 @@ impl EGLGraphicsBackend for WinitGraphicsBackend { } } -/// Errors that may happen when driving the event loop of `WinitInputBackend` +/// Errors that may happen when driving the event loop of [`WinitInputBackend`] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum WinitInputError { - /// The underlying `winit` `Window` was closed. No further events can be processed. + /// The underlying [`WinitWindow`] was closed. No further events can be processed. /// - /// See `WinitInputBackend::dispatch_new_events`. + /// See `dispatch_new_events`. WindowClosed, } -impl error::Error for WinitInputError { +impl ::std::error::Error for WinitInputError { fn description(&self) -> &str { match *self { WinitInputError::WindowClosed => "Glutin Window was closed", @@ -338,7 +345,7 @@ impl fmt::Display for WinitInputError { } } #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -/// Winit-Backend internal event wrapping `winit`'s types into a `KeyboardKeyEvent` +/// Winit-Backend internal event wrapping `winit`'s types into a [`KeyboardKeyEvent`] pub struct WinitKeyboardInputEvent { time: u32, key: u32, @@ -367,7 +374,7 @@ impl KeyboardKeyEvent for WinitKeyboardInputEvent { } #[derive(Clone)] -/// Winit-Backend internal event wrapping `winit`'s types into a `PointerMotionAbsoluteEvent` +/// Winit-Backend internal event wrapping `winit`'s types into a [`PointerMotionAbsoluteEvent`] pub struct WinitMouseMovedEvent { size: Rc>, time: u32, @@ -404,7 +411,7 @@ impl PointerMotionAbsoluteEvent for WinitMouseMovedEvent { } #[derive(Debug, Clone, Copy, PartialEq)] -/// Winit-Backend internal event wrapping `winit`'s types into a `PointerAxisEvent` +/// Winit-Backend internal event wrapping `winit`'s types into a [`PointerAxisEvent`] pub struct WinitMouseWheelEvent { time: u32, delta: MouseScrollDelta, @@ -442,7 +449,7 @@ impl PointerAxisEvent for WinitMouseWheelEvent { } #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -/// Winit-Backend internal event wrapping `winit`'s types into a `PointerButtonEvent` +/// Winit-Backend internal event wrapping `winit`'s types into a [`PointerButtonEvent`] pub struct WinitMouseInputEvent { time: u32, button: WinitMouseButton, @@ -466,7 +473,7 @@ impl PointerButtonEvent for WinitMouseInputEvent { } #[derive(Clone)] -/// Winit-Backend internal event wrapping `winit`'s types into a `TouchDownEvent` +/// Winit-Backend internal event wrapping `winit`'s types into a [`TouchDownEvent`] pub struct WinitTouchStartedEvent { size: Rc>, time: u32, @@ -513,7 +520,7 @@ impl TouchDownEvent for WinitTouchStartedEvent { } #[derive(Clone)] -/// Winit-Backend internal event wrapping `winit`'s types into a `TouchMotionEvent` +/// Winit-Backend internal event wrapping `winit`'s types into a [`TouchMotionEvent`] pub struct WinitTouchMovedEvent { size: Rc>, time: u32, @@ -573,7 +580,7 @@ impl TouchUpEvent for WinitTouchEndedEvent { } #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -/// Winit-Backend internal event wrapping `winit`'s types into a `TouchCancelEvent` +/// Winit-Backend internal event wrapping `winit`'s types into a [`TouchCancelEvent`] pub struct WinitTouchCancelledEvent { time: u32, id: u64, @@ -655,17 +662,17 @@ impl InputBackend for WinitInputBackend { &mut self.input_config } - /// Processes new events of the underlying event loop to drive the set `InputHandler`. + /// Processes new events of the underlying event loop to drive the set [`InputHandler`]. /// /// You need to periodically call this function to keep the underlying event loop and - /// `Window` active. Otherwise the window may no respond to user interaction and no - /// input events will be received by a set `InputHandler`. + /// [`WinitWindow`] active. Otherwise the window may no respond to user interaction and no + /// input events will be received by a set [`InputHandler`]. /// - /// Returns an error if the `Window` the window has been closed. Calling - /// `dispatch_new_events` again after the `Window` has been closed is considered an + /// Returns an error if the [`WinitWindow`] the window has been closed. Calling + /// `dispatch_new_events` again after the [`WinitWindow`] has been closed is considered an /// application error and unspecified behaviour may occur. /// - /// The linked `WinitGraphicsBackend` will error with a lost `Context` and should + /// The linked [`WinitGraphicsBackend`] will error with a lost context and should /// not be used anymore as well. fn dispatch_new_events(&mut self) -> ::std::result::Result<(), WinitInputError> { let mut closed = false; diff --git a/src/lib.rs b/src/lib.rs index 9e11b51..25e5e19 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,7 +1,7 @@ #![warn(missing_docs)] //! **Smithay: the Wayland compositor smithy** //! -//! Most entry points in the modules can take an optional `slog::Logger` as argument +//! Most entry points in the modules can take an optional [`slog::Logger`](::slog::Logger) as argument //! that will be used as a drain for logging. If `None` is provided, they'll log to `slog-stdlog`. // `error_chain!` can recurse deeply diff --git a/src/wayland/compositor/mod.rs b/src/wayland/compositor/mod.rs index 6388948..f795c50 100644 --- a/src/wayland/compositor/mod.rs +++ b/src/wayland/compositor/mod.rs @@ -2,7 +2,8 @@ //! //! This module provides automatic handling of surfaces, subsurfaces //! and region Wayland objects, by registering an implementation for -//! for the `wl_compositor` and `wl_subcompositor` globals. +//! for the [`wl_compositor`](wayland_server::protocol::wl_compositor) +//! and [`wl_subcompositor`](wayland_server::protocol::wl_subcompositor) globals. //! //! ## Why use this implementation //! @@ -22,8 +23,8 @@ //! //! ### Initialization //! -//! To initialize this implementation, use the `compositor_init` method provided -//! by this module. It'll require you to first define as few things, as shown in +//! To initialize this implementation, use the [`compositor_init`](::wayland::compositor::compositor_init) +//! method provided by this module. It'll require you to first define as few things, as shown in //! this example: //! //! ``` @@ -66,15 +67,17 @@ //! //! As you can see in the previous example, in the end we are retrieving a token from //! the `init` function. This token is necessary to retrieve the metadata associated with -//! a surface. It can be cloned. See `CompositorToken` for the details of what it enables you. +//! a surface. It can be cloned. See [`CompositorToken`](::wayland::compositor::CompositorToken) +//! for the details of what it enables you. //! -//! The surface metadata is held in the `SurfaceAttributes` struct. In contains double-buffered -//! state pending from the client as defined by the protocol for `wl_surface`, as well as your -//! user-defined type holding any data you need to have associated with a struct. See its -//! documentation for details. +//! The surface metadata is held in the [`SurfaceAttributes`](::wayland::compositor::SurfaceAttributes) +//! struct. In contains double-buffered state pending from the client as defined by the protocol for +//! [`wl_surface`](wayland_server::protocol::wl_surface), as well as your user-defined type holding +//! any data you need to have associated with a struct. See its documentation for details. //! -//! This `CompositorToken` also provides access to the metadata associated with the role of the -//! surfaces. See the documentation of the `roles` submodule for a detailed explanation. +//! This [`CompositorToken`](::wayland::compositor::CompositorToken) also provides access to the metadata associated with the role of the +//! surfaces. See the documentation of the [`roles`](::wayland::compositor::roles) submodule +//! for a detailed explanation. use std::{cell::RefCell, rc::Rc, sync::Mutex}; @@ -117,7 +120,8 @@ struct Marker { /// Data associated with a surface, aggregated by the handlers /// /// Most of the fields of this struct represent a double-buffered state, which -/// should only be applied once a `commit` request is received from the surface. +/// should only be applied once a [`commit`](::wayland::compositor::SurfaceEvent::Commit) +/// request is received from the surface. /// /// You are responsible for setting those values as you see fit to avoid /// processing them two times. @@ -232,7 +236,8 @@ impl Default for RegionAttributes { /// A Compositor global token /// /// This token can be cloned at will, and is the entry-point to -/// access data associated with the `wl_surface` and `wl_region` managed +/// access data associated with the [`wl_surface`](wayland_server::protocol::wl_surface) +/// and [`wl_region`](wayland_server::protocol::wl_region) managed /// by the `CompositorGlobal` that provided it. pub struct CompositorToken { _data: ::std::marker::PhantomData<*mut U>, @@ -292,7 +297,7 @@ where /// - a mutable reference to its surface attribute data /// - a mutable reference to its role data, /// - a custom value that is passed in a fold-like manner, but only from the output of a parent - /// to its children. See `TraversalAction` for details. + /// to its children. See [`TraversalAction`] for details. /// /// If the surface not managed by the `CompositorGlobal` that provided this token, this /// will panic (having more than one compositor is not supported). @@ -315,7 +320,7 @@ where /// in a depth-first order. This matches the reverse of the order in which the surfaces are /// supposed to be drawn: top-most first. /// - /// Behavior is the same as `with_surface_tree_upward`. + /// Behavior is the same as [`with_surface_tree_upward`](CompositorToken::with_surface_tree_upward). pub fn with_surface_tree_downward( &self, surface: &Resource, @@ -438,11 +443,12 @@ impl CompositorToken { } } -/// Create new `wl_compositor` and `wl_subcompositor` globals. +/// Create new [`wl_compositor`](wayland_server::protocol::wl_compositor) +/// and [`wl_subcompositor`](wayland_server::protocol::wl_subcompositor) globals. /// /// The globals are directly registered into the event loop, and this function -/// returns a `CompositorToken` which you'll need access the data associated to -/// the `wl_surface`s. +/// returns a [`CompositorToken`] which you'll need access the data associated to +/// the [`wl_surface`](wayland_server::protocol::wl_surface)s. /// /// It also returns the two global handles, in case you wish to remove these /// globals from the event loop in the future. @@ -491,7 +497,7 @@ where pub enum SurfaceEvent { /// The double-buffered state has been validated by the client /// - /// At this point, the pending state that has been accumulated in the `SurfaceAttributes` associated + /// At this point, the pending state that has been accumulated in the [`SurfaceAttributes`] associated /// to this surface should be integrated into the current state of the surface. /// /// See [`wayland_server::protocol::wl_surface::Implementation::commit`](https://docs.rs/wayland-server/0.10.1/wayland_server/protocol/wl_surface/struct.Implementation.html#structfield.commit) @@ -499,8 +505,8 @@ pub enum SurfaceEvent { Commit, /// The client asks to be notified when would be a good time to update the contents of this surface /// - /// You must keep the provided `WlCallback` and trigger it at the appropriate time by calling - /// its `done()` method. + /// You must keep the provided [`WlCallback`](wayland_server::protocol::wl_callback::WlCallback) + /// and trigger it at the appropriate time by calling its `done()` method. /// /// See [`wayland_server::protocol::wl_surface::Implementation::frame`](https://docs.rs/wayland-server/0.10.1/wayland_server/protocol/wl_surface/struct.Implementation.html#structfield.frame) /// for more details diff --git a/src/wayland/compositor/roles.rs b/src/wayland/compositor/roles.rs index 455702e..736f7cb 100644 --- a/src/wayland/compositor/roles.rs +++ b/src/wayland/compositor/roles.rs @@ -76,12 +76,14 @@ //! as well as implement a few trait for it, allowing it to be used by //! all smithay handlers: //! -//! - The trait `RoleType`, which defines it as a type handling roles -//! - For each of your roles, the trait `Role` (where `Token` is your -//! token type), marking its ability to handle this given role. +//! - The trait [`RoleType`](::wayland::compositor::roles::RoleType), +//! which defines it as a type handling roles +//! - For each of your roles, the trait [`Role`](::wayland::compositor::roles::Role) +//! (where `Token` is your token type), marking its ability to handle this given role. //! //! All handlers that handle a specific role will require you to provide -//! them with a `CompositorToken` where `R: Role`. +//! them with a [`CompositorToken`](::wayland::compositor::CompositorToken) +//! where `R: Role`. //! //! See the documentation of these traits for their specific definition and //! capabilities. @@ -98,13 +100,13 @@ pub trait RoleType { /// Check if the associated surface has a role /// /// Only reports if the surface has any role or no role. - /// To check for a role in particular, see `Role::has`. + /// To check for a role in particular, see [`Role::has`]. fn has_role(&self) -> bool; } -/// A trait representing the capability of a `RoleType` to handle a given role +/// A trait representing the capability of a [`RoleType`] to handle a given role /// -/// This trait allows to interact with the different roles a `RoleType` can +/// This trait allows to interact with the different roles a [`RoleType`] can /// handle. /// /// This trait is meant to be used generically, for example, to retrieve the @@ -115,7 +117,8 @@ pub trait RoleType { /// .expect("The surface does not have this role."); /// ``` /// -/// The methods of this trait are mirrored on `CompositorToken` for easy +/// The methods of this trait are mirrored on +/// [`CompositorToken`](::wayland::compositor::CompositorToken) for easy /// access to the role data of the surfaces. /// /// Note that if a role is automatically handled for you by a Handler provided diff --git a/src/wayland/data_device/mod.rs b/src/wayland/data_device/mod.rs index 1ed1e50..e883cd6 100644 --- a/src/wayland/data_device/mod.rs +++ b/src/wayland/data_device/mod.rs @@ -6,11 +6,11 @@ //! //! This module provides 2 main freestanding functions: //! -//! - `init_data_device`: this function must be called during the compositor startup to initialize -//! the data device logic -//! - `set_data_device_focus`: this function sets the data device focus for a given seat; you'd -//! typically call it whenever the keyboard focus changes, to follow it (for example in the focus -//! hook of your keyboards) +//! - [`init_data_device`](::wayland::data_device::init_data_device): this function must be called +//! during the compositor startup to initialize the data device logic +//! - [`set_data_device_focus`](::wayland::data_device::set_data_device_focus): this function sets +//! the data device focus for a given seat; you'd typically call it whenever the keyboard focus +//! changes, to follow it (for example in the focus hook of your keyboards) //! //! Using these two functions is enough for your clients to be able to interact with each other using //! the data devices. @@ -18,10 +18,11 @@ //! The module also provides additionnal mechanisms allowing your compositor to see and interact with //! the contents of the data device: //! -//! - You can provide a callback closure to `init_data_device` to peek into the the actions of your clients -//! - the freestanding function `set_data_device_selection` allows you to set the contents of the selection -//! for your clients -//! - the freestanding function `start_dnd` allows you to initiate a drag'n'drop event from the compositor +//! - You can provide a callback closure to [`init_data_device`](::wayland::data_device::init_data_device) +//! to peek into the the actions of your clients +//! - the freestanding function [`set_data_device_selection`](::wayland::data_device::set_data_device_selection) +//! allows you to set the contents of the selection for your clients +//! - the freestanding function [`start_dnd`](::wayland::data_device::start_dnd) allows you to initiate a drag'n'drop event from the compositor //! itself and receive interactions of clients with it via an other dedicated callback. //! //! The module also defines the `DnDIconRole` that you need to insert into your compositor roles enum, to @@ -269,15 +270,16 @@ impl SeatData { /// /// You can provide a callback to peek into the actions of your clients over the data devices /// (allowing you to retrieve the current selection buffer, or intercept DnD data). See the -/// `DataDeviceEvent` type for details about what notifications you can receive. Note that this +/// [`DataDeviceEvent`] type for details about what notifications you can receive. Note that this /// closure will not receive notifications about dnd actions the compositor initiated, see -/// `start_dnd` for details about that. +/// [`start_dnd`] for details about that. /// /// You also need to provide a `(DndAction, DndAction) -> DndAction` closure that will arbitrate /// the choice of action resulting from a drag'n'drop session. Its first argument is the set of /// available actions (which is the intersection of the actions supported by the source and targets) /// and the second argument is the preferred action reported by the target. If no action should be -/// chosen (and thus the drag'n'drop should abort on drop), return `DndAction::empty()`. +/// chosen (and thus the drag'n'drop should abort on drop), return +/// [`DndAction::empty()`](wayland_server::protocol::wl_data_device_manager::DndAction::empty). pub fn init_data_device( display: &mut Display, callback: C, @@ -329,7 +331,7 @@ pub fn set_data_device_focus(seat: &Seat, client: Option) { /// You need to provide the available mime types for this selection. /// /// Whenever a client requests to read the selection, your callback will -/// receive a `DataDeviceEvent::SendSelection` event. +/// receive a [`DataDeviceEvent::SendSelection`] event. pub fn set_data_device_selection(seat: &Seat, mime_types: Vec) { // TODO: same question as in set_data_device_focus seat.user_data().insert_if_missing(|| { @@ -350,7 +352,7 @@ pub fn set_data_device_selection(seat: &Seat, mime_types: Vec) { /// Start a drag'n'drop from a ressource controlled by the compositor /// /// You'll receive events generated by the interaction of clients with your -/// drag'n'drop in the provided callback. See `SeverDndEvent` for details about +/// drag'n'drop in the provided callback. See [`ServerDndEvent`] for details about /// which events can be generated and what response is expected from you to them. pub fn start_dnd(seat: &Seat, serial: u32, metadata: SourceMetadata, callback: C) where diff --git a/src/wayland/data_device/server_dnd_grab.rs b/src/wayland/data_device/server_dnd_grab.rs index 9de8b69..b48b49e 100644 --- a/src/wayland/data_device/server_dnd_grab.rs +++ b/src/wayland/data_device/server_dnd_grab.rs @@ -10,7 +10,7 @@ use wayland::seat::{AxisFrame, PointerGrab, PointerInnerHandle, Seat}; use super::{DataDeviceData, SeatData}; -/// Event generated by the interactions of clients with a server innitiated drag'n'drop +/// Event generated by the interactions of clients with a server initiated drag'n'drop pub enum ServerDndEvent { /// The client chose an action Action(DndAction), diff --git a/src/wayland/mod.rs b/src/wayland/mod.rs index b61ba8d..8ad4276 100644 --- a/src/wayland/mod.rs +++ b/src/wayland/mod.rs @@ -21,7 +21,7 @@ pub mod seat; pub mod shell; pub mod shm; -/// A global `SerialCounter` for use in your compositor. +/// A global [`SerialCounter`] for use in your compositor. /// /// Is is also used internally by some parts of Smithay. pub static SERIAL_COUNTER: SerialCounter = SerialCounter { diff --git a/src/wayland/output/mod.rs b/src/wayland/output/mod.rs index 3832f3c..8c2ae77 100644 --- a/src/wayland/output/mod.rs +++ b/src/wayland/output/mod.rs @@ -7,12 +7,12 @@ //! //! # How to use it //! -//! You need to instantiate an `Output` for each output global you want -//! to advertise to clients. +//! You need to instantiate an [`Output`](::wayland::output::Output) +//! for each output global you want to advertise to clients. //! -//! Just add it to your Display using the `Output::new(..)` method. -//! You can use the returned `Output` to change the properties of your -//! output (if the current resolution mode changes for example), +//! Just add it to your Display using the [`Output::new(..)`](::wayland::output::Output::new) +//! method. You can use the returned [`Output`](::wayland::output::Output) to change +//! the properties of your output (if the current resolution mode changes for example), //! it'll automatically forward any changes to the clients. //! //! ``` @@ -306,7 +306,7 @@ impl Output { } } - /// Check is given `wl_output` instance is managed by this `Output`. + /// Check is given [`wl_output`](WlOutput) instance is managed by this [`Output`]. pub fn owns(&self, output: &Resource) -> bool { self.inner .lock() diff --git a/src/wayland/seat/keyboard.rs b/src/wayland/seat/keyboard.rs index 782fdb6..7c71dfc 100644 --- a/src/wayland/seat/keyboard.rs +++ b/src/wayland/seat/keyboard.rs @@ -275,9 +275,9 @@ struct KbdArc { /// This handle gives you 2 main ways to interact with the keyboard handling: /// /// - set the current focus for this keyboard: designing the surface that will receive the key inputs -/// using the `KeyboardHandle::set_focus` method. +/// using the [`KeyboardHandle::set_focus`] method. /// - process key inputs from the input backend, allowing them to be caught at the compositor-level -/// or forwarded to the client. See the documentation of the `KeyboardHandle::input` method for +/// or forwarded to the client. See the documentation of the [`KeyboardHandle::input`] method for /// details. #[derive(Clone)] pub struct KeyboardHandle { @@ -295,7 +295,7 @@ impl KeyboardHandle { /// returns false, the input will not be sent to the client. This mechanism can be used to /// implement compositor-level key bindings for example. /// - /// The module `smithay::keyboard::keysyms` exposes definitions of all possible keysyms + /// The module [`wayland::seat::keysyms`](::wayland::seat::keysyms) exposes definitions of all possible keysyms /// to be compared against. This includes non-character keysyms, such as XF86 special keys. pub fn input(&self, keycode: u32, state: KeyState, serial: u32, time: u32, filter: F) where @@ -357,8 +357,9 @@ impl KeyboardHandle { /// Set the current focus of this keyboard /// /// If the new focus is different from the previous one, any previous focus - /// will be sent a `wl_keyboard::leave` event, and if the new focus is not `None`, - /// a `wl_keyboard::enter` event will be sent. + /// will be sent a [`wl_keyboard::Event::Leave`](wayland_server::protocol::wl_keyboard::Event::Leave) + /// event, and if the new focus is not `None`, + /// a [`wl_keyboard::Event::Enter`](wayland_server::protocol::wl_keyboard::Event::Enter) event will be sent. pub fn set_focus(&self, focus: Option<&Resource>, serial: u32) { let mut guard = self.arc.internal.lock().unwrap(); diff --git a/src/wayland/seat/mod.rs b/src/wayland/seat/mod.rs index d699667..77050f8 100644 --- a/src/wayland/seat/mod.rs +++ b/src/wayland/seat/mod.rs @@ -38,7 +38,8 @@ //! Currently, only pointer and keyboard capabilities are supported by //! smithay. //! -//! You can add these capabilities via methods of the `Seat` struct: `add_keyboard`, `add_pointer`. +//! You can add these capabilities via methods of the [`Seat`](::wayland::seat::Seat) struct: +//! [`add_keyboard`](::wayland::seat::Seat::add_keyboard), [`add_pointer`](::wayland::seat::Seat::add_pointer). //! These methods return handles that can be cloned and sent across thread, so you can keep one around //! in your event-handling code to forward inputs to your clients. @@ -101,7 +102,7 @@ impl Inner { /// This struct gives you access to the control of the /// capabilities of the associated seat. /// -/// It is directly inserted in the event loop by its `new` method. +/// It is directly inserted in the event loop by its [`new`](Seat::new) method. /// /// This is an handle to the inner logic, it can be cloned and shared accross /// threads. @@ -160,7 +161,7 @@ impl Seat { (seat, global) } - /// Attempt to retrieve a `Seat` from an existing resource + /// Attempt to retrieve a [`Seat`] from an existing resource pub fn from_resource(seat: &Resource) -> Option { seat.user_data::>().cloned().map(|arc| Seat { arc }) } @@ -172,8 +173,8 @@ impl Seat { /// Adds the pointer capability to this seat /// - /// You are provided a `PointerHandle`, which allows you to send input events - /// to this keyboard. This handle can be cloned and sent across threads. + /// You are provided a [`PointerHandle`], which allows you to send input events + /// to this pointer. This handle can be cloned and sent across threads. /// /// Calling this method on a seat that already has a pointer capability /// will overwrite it, and will be seen by the clients as if the @@ -245,7 +246,7 @@ impl Seat { /// Adds the keyboard capability to this seat /// - /// You are provided a `KbdHandle`, which allows you to send input events + /// You are provided a [`KeyboardHandle`], which allows you to send input events /// to this keyboard. This handle can be cloned and sent across threads. /// /// You also provide a Model/Layout/Variant/Options specification of the @@ -324,7 +325,7 @@ impl Seat { } } - /// Checks whether a given `WlSeat` is associated with this `Seat` + /// Checks whether a given [`WlSeat`](wl_seat::WlSeat) is associated with this [`Seat`] pub fn owns(&self, seat: &Resource) -> bool { let inner = self.arc.inner.lock().unwrap(); inner.known_seats.iter().any(|s| s.equals(seat)) diff --git a/src/wayland/seat/pointer.rs b/src/wayland/seat/pointer.rs index 7a57600..15ce763 100644 --- a/src/wayland/seat/pointer.rs +++ b/src/wayland/seat/pointer.rs @@ -124,7 +124,7 @@ impl PointerInternal { /// clients. /// /// When sending events using this handle, they will be intercepted by a pointer -/// grab if any is active. See the `PointerGrab` trait for details. +/// grab if any is active. See the [`PointerGrab`] trait for details. #[derive(Clone)] pub struct PointerHandle { inner: Arc>, @@ -213,7 +213,6 @@ impl PointerHandle { /// Start an axis frame /// /// A single frame will group multiple scroll events as if they happened in the same instance. - /// Dropping the returned `PointerAxisHandle` will group the events together. pub fn axis(&self, details: AxisFrame) { self.inner.lock().unwrap().with_grab(|mut handle, grab| { grab.axis(&mut handle, details); @@ -228,9 +227,9 @@ impl PointerHandle { /// the underlying surfaces will no longer receive classic pointer event, but rather special events. /// /// This trait is the interface to intercept regular pointer events and change them as needed, its -/// interface mimics the `PointerHandle` interface. +/// interface mimics the [`PointerHandle`] interface. /// -/// If your logic decides that the grab should end, both `PointerInnerHandle` and `PointerHandle` have +/// If your logic decides that the grab should end, both [`PointerInnerHandle`] and [`PointerHandle`] have /// a method to change it. /// /// When your grab ends (either as you requested it or if it was forcefully cancelled by the server), @@ -492,7 +491,7 @@ impl AxisFrame { /// This event is optional, if no source is known, you can ignore this call. /// Only one source event is allowed per frame. /// - /// Using the `AxisSource::Finger` requires a stop event to be send, + /// Using the [`AxisSource::Finger`] requires a stop event to be send, /// when the user lifts off the finger (not necessarily in the same frame). pub fn source(mut self, source: AxisSource) -> Self { self.source = Some(source); @@ -532,7 +531,7 @@ impl AxisFrame { /// Notification of stop of scrolling on an axis. /// - /// This event is required for sources of the `AxisSource::Finger` type + /// This event is required for sources of the [`AxisSource::Finger`] type /// and otherwise optional. pub fn stop(mut self, axis: Axis) -> Self { match axis { diff --git a/src/wayland/shell/legacy/mod.rs b/src/wayland/shell/legacy/mod.rs index 2269284..d02a56e 100644 --- a/src/wayland/shell/legacy/mod.rs +++ b/src/wayland/shell/legacy/mod.rs @@ -23,9 +23,9 @@ //! //! ### Initialization //! -//! To initialize this handler, simple use the `wl_shell_init` function provided in this -//! module. You will need to provide it the `CompositorToken` you retrieved from an -//! instantiation of the compositor handler provided by smithay. +//! To initialize this handler, simple use the [`wl_shell_init`](::wayland::shell::legacy::wl_shell_init) +//! function provided in this module. You will need to provide it the [`CompositorToken`](::wayland::compositor::CompositorToken) +//! you retrieved from an instantiation of the compositor handler provided by smithay. //! //! ```no_run //! # extern crate wayland_server; @@ -85,7 +85,7 @@ use wayland_server::{ mod wl_handlers; -/// Metadata associated with the `xdg_surface` role +/// Metadata associated with the `wl_surface` role pub struct ShellSurfaceRole { /// Title of the surface pub title: String, @@ -133,7 +133,7 @@ where /// Send a ping request to this shell surface /// - /// You'll receive the reply as a `ShellRequest::Pong` request + /// You'll receive the reply as a [`ShellRequest::Pong`] request /// /// A typical use is to start a timer at the same time you send this ping /// request, and cancel it when you receive the pong. If the timer runs diff --git a/src/wayland/shell/xdg/mod.rs b/src/wayland/shell/xdg/mod.rs index c4f3150..08b4151 100644 --- a/src/wayland/shell/xdg/mod.rs +++ b/src/wayland/shell/xdg/mod.rs @@ -21,9 +21,9 @@ //! //! ### Initialization //! -//! To initialize this handler, simple use the `xdg_shell_init` function provided in this -//! module. You will need to provide it the `CompositorToken` you retrieved from an -//! instantiation of the compositor global provided by smithay. +//! To initialize this handler, simple use the [`xdg_shell_init`](::wayland::shell::xdg::xdg_shell_init) function provided in this +//! module. You will need to provide it the [`CompositorToken`](::wayland::compositor::CompositorToken) +//! you retrieved from an instantiation of the compositor global provided by smithay. //! //! ```no_run //! # extern crate wayland_server; @@ -73,17 +73,22 @@ //! //! There are mainly 3 kind of objects that you'll manipulate from this implementation: //! -//! - `ShellClient`: This is a handle representing an instantiation of a shell global +//! - [`ShellClient`](::wayland::shell::xdg::ShellClient): +//! This is a handle representing an instantiation of a shell global //! you can associate client-wise metadata to it (this is the `MyShellData` type in //! the example above). -//! - `ToplevelSurface`: This is a handle representing a toplevel surface, you can -//! retrieve a list of all currently alive toplevel surface from the `ShellState`. -//! - `PopupSurface`: This is a handle representing a popup/tooltip surface. Similarly, -//! you can get a list of all currently alive popup surface from the `ShellState`. +//! - [`ToplevelSurface`](::wayland::shell::xdg::ToplevelSurface): +//! This is a handle representing a toplevel surface, you can +//! retrieve a list of all currently alive toplevel surface from the +//! [`ShellState`](::wayland::shell::xdg::ShellState). +//! - [`PopupSurface`](::wayland::shell::xdg::PopupSurface): +//! This is a handle representing a popup/tooltip surface. Similarly, +//! you can get a list of all currently alive popup surface from the +//! [`ShellState`](::wayland::shell::xdg::ShellState). //! //! You'll obtain these objects though two means: either via the callback methods of -//! the subhandler you provided, or via methods on the `ShellState` that you are given -//! (in an `Arc>`) as return value of the `init` function. +//! the subhandler you provided, or via methods on the [`ShellState`](::wayland::shell::xdg::ShellState) +//! that you are given (in an `Arc>`) as return value of the `init` function. use std::{ cell::RefCell, @@ -408,7 +413,7 @@ where /// Send a ping request to this shell client /// - /// You'll receive the reply as a `XdgRequest::ClientPong` request. + /// You'll receive the reply as a [`XdgRequest::ClientPong`] request. /// /// A typical use is to start a timer at the same time you send this ping /// request, and cancel it when you receive the pong. If the timer runs @@ -843,7 +848,7 @@ pub enum XdgRequest { }, /// A new toplevel surface was created /// - /// You likely need to send a `ToplevelConfigure` to the surface, to hint the + /// You likely need to send a [`ToplevelConfigure`] to the surface, to hint the /// client as to how its window should be NewToplevel { /// the surface @@ -851,7 +856,7 @@ pub enum XdgRequest { }, /// A new popup surface was created /// - /// You likely need to send a `PopupConfigure` to the surface, to hint the + /// You likely need to send a [`PopupConfigure`] to the surface, to hint the /// client as to how its popup should be NewPopup { /// the surface diff --git a/src/wayland/shm/mod.rs b/src/wayland/shm/mod.rs index 9fd30cb..fe673a6 100644 --- a/src/wayland/shm/mod.rs +++ b/src/wayland/shm/mod.rs @@ -36,8 +36,9 @@ //! # } //! ``` //! -//! Then, when you have a `WlBuffer` and need to retrieve its contents, use the -//! `with_buffer_contents` function to do it: +//! Then, when you have a [`WlBuffer`](wayland_server::protocol::wl_buffer::WlBuffer) +//! and need to retrieve its contents, use the +//! [`with_buffer_contents`](::wayland::shm::with_buffer_contents) function to do it: //! //! ``` //! # extern crate wayland_server; @@ -103,8 +104,8 @@ pub struct ShmGlobalData { /// as they are required by the protocol. Formats given as argument /// as additionally advertized. /// -/// The global is directly created on the provided `Display`, and this function -/// returns the global handle, in case you wish to remove this global in +/// The global is directly created on the provided [`Display`](wayland_server::Display), +/// and this function returns the global handle, in case you wish to remove this global in /// the future. pub fn init_shm_global( display: &mut Display,