server: crate docs

wayland-server/src/lib.rs

@@ -1,3 +1,97 @@
+//! Server-side Wayland connector
+//!
+//! ## Overview
+//!
+//! This crate provides the interfaces and machinery to safely create server
+//! for the wayland protocol. It is a rust wrapper around the `libwayland-server.so`
+//! C library.
+//!
+//! The wayland protocol revolves around the creation of various objects and the exchange
+//! of messages associated to these objects. Whenever a client connects, a `Display` object
+//! is automatically created in their object space, which they use as a root to create new
+//! objects and bootstrap their state.
+//!
+//! ## Protocol and messages handling model
+//!
+//! The protocol being bi-directional, you can send and receive messages. Sending messages is
+//! done via methods of `Resource<_>` objects, receiving and handling them is done by providing
+//! implementations.
+//!
+//! ### Resources
+//!
+//! The protocol and message model is very similar to the one of `wayland-client`, with the
+//! main difference being that the handles to objects are represented by the `Resource<I>`
+//! type.
+//!
+//! These resources are used to senf messages to the clients (they are called "events" in the
+//! wayland context). This is done by the `Resource::<I>::send(..)` method.
+//!
+//! There is not a 1 to 1 mapping between `Resource<I>` instances and protocol objects. Rather,
+//! you can think of `Resource<I>` as an `Rc`-like handle to a wayland object. Multiple instances
+//! of it can exist referring to the same protocol object.
+//!
+//! Similarly, the lifetimes of the protocol objects and the `Resource<I>` are not tighly tied.
+//! As protocol objects are created and destroyed by protocol messages, it can happen that an object
+//! gets destroyed while one or more `Resource<I>` still refers to it. In such case, these resources
+//! will be disabled and their `alive()` method will start to return `false`. Events that are
+//! subsequently sent to them are ignored.
+//!
+//! ### Implementations
+//!
+//! To receive and process messages from the clients to you (in wayland context they are
+//! called "requests"), you need to provide an `Implementation` for each wayland object
+//! created in the protocol session. Whenever a new protocol object is created, you will
+//! receive a `NewResource<I>` object. Providing an implementation via its `implement()` method
+//! will turn it into a regular `Resource<I>` object.
+//!
+//! **All objects must be implemented**, even if it is an implementation doing nothing.
+//! Failure to do so (by dropping the `NewResource<I>` for example) can cause future fatal
+//! protocol errors if the client tries to send a request to this object.
+//!
+//! An implementation is just a struct implementing the `Implementation<Resource<I>, I::Requests>`
+//! trait, where `I` is the interface of the considered object:
+//!
+//! ```
+//! // Example implementation for the wl_surface interface
+//! use wayland_server::Resource;
+//! use wayland_server::protocol::wl_surface;
+//! use wayland_server::commons::Implementation;
+//!
+//! struct MyImpl {
+//!    // ...
+//! }
+//!
+//! impl Implementation<Resource<wl_surface::WlSurface>, wl_surface::Requests> for MyImpl {
+//!     fn receive(&mut self, msg: wl_surface::Requests, resource: Resource<wl_surface::WlSurface>) {
+//!         // process the message...
+//!     }
+//! }
+//! # fn main() {}
+//! ```
+//!
+//! The trait is also automatically implemented for `FnMut(I::Requests, Resource<I>)` closures,
+//! so you can use them for simplicity if a full struct would be too cumbersome.
+//!
+//! The `Resource<I>` passed to your implementation is garanteed to be alive (as it just received
+//! a request), unless the exact message received is a destructor (which is indicated in the API
+//! documentations).
+//!
+//! ## Event loops and general structure
+//!
+//! The core of your server is the `Display` object. It represent the ability of your program to
+//! process wayland messages. Once this object is created, you can configure it to listen on one
+//! or more sockets for incoming client connections (see the `Display` docs for details).
+//!
+//! The crate also provides an event loop structure. An `EventLoop` is automatically created at the
+//! same time as the `Display`, and it will handle the connections of your wayland clients. See the
+//! `EventLoop` API documentation for explanations of its use.
+//!
+//! It is also possible to both create other event loops and insert other kind of sources of events
+//! to the event loops. These functions are typically useful to integrate, as a wayland compositor,
+//! with other parts of the system (typically listening on file destrictor describing input devices).
+//! Adding sources to an event loop is done via the `LoopToken` type, that is retrieved by the
+//! `token()` method of `EventLoop`. See their documentations for more details.
+
 #![warn(missing_docs)]
 
 #[macro_use]