data_device: module-level docs

src/wayland/data_device/mod.rs

@@ -1,3 +1,29 @@
+//! Utilities for manipulating the data devices
+//!
+//! The data device is wayland's abstraction to represent both selection (copy/paste) and
+//! drag'n'drop actions. This module provides logic to handle this part of the protocol.
+//! Selection and drag'n'drop are per-seat notions.
+//!
+//! 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)
+//!
+//! Using these two functions is enough for your clients to be able to interact with each other using
+//! the data devices.
+//!
+//! 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
+//!   itself and receive interactions of clients with it via an other dedicated callback.
+
 use std::os::unix::io::RawFd;
 use std::sync::{Arc, Mutex};
 
@@ -186,7 +212,13 @@ impl SeatData {
 
 /// Initialize the data device global
 ///
-/// You need to provide a `(DndAction, DndAction) -> DndAction` closure that will arbitrate
+/// 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
+/// closure will not receive notifications about dnd actions the compositor initiated, see
+/// `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
@@ -254,7 +286,8 @@ pub fn set_data_device_selection(seat: &Seat, mime_types: Vec<String>) {
 /// 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.
+/// drag'n'drop in the provided callback. See `SeverDndEvent` for details about
+/// which events can be generated and what response is expected from you to them.
 pub fn start_dnd<C>(seat: &Seat, serial: u32, metadata: SourceMetadata, callback: C)
 where
     C: FnMut(ServerDndEvent) + Send + 'static,