Update CHANGELOG and docs

CHANGELOG.md

@@ -4,9 +4,9 @@
 
 - [scanner] Generate `EventHandler` and `RequestHandler` traits for trait-based event
   and request handling (as opposed to manually matching on enums).
-- [client & server] **Breaking**: Change `NewProxy/NewRequest::implement()` to accept
+- **Breaking** [client/server] Change `NewProxy/NewRequest::implement()` to accept
   a handler struct which implements the corresponding `EventHandler/RequestHandler` trait.
-- [client & server] Introduce `NewProxy/NewRequest::implement_closure()` which behaves
+- [client/server] Introduce `NewProxy/NewRequest::implement_closure()` which behaves
   like the previous `NewProxy/NewRequest::implement()` and
   `NewProxy/NewRequest::implement_dummy()` which adds an empty implementation.
 - **Breaking** [client/server] `implement()` method will now runtime-track which thread it
@@ -16,6 +16,19 @@
 - **Breaking** [server] When the `native_lib` cargo feature is active, none of the types
   of the server crate are threadsafe, as the underlying C lib actually never supported it.
   The rust implementation remains threadsafe.
+- **Breaking** [client/server] `Proxy<I>` and `Resource<I>` are now wrapped in their
+  corresponding `I` objects. All `RequestsTrait` traits were removed and methods for
+  sending requests and events are now part of the `I` objects themselves. This means that
+  it is no longer needed to import all necessary `RequestsTrait` traits into scope and
+  deal with their name clashes. This also means that a lot of `Proxy<I>` and `Resource<I>`
+  types were replaced with just `I`. To convert between `Proxy/Resource<I>` and `I`,
+  `From` implementations are provided (use `.into()`), as well as an
+  `AsRef<Proxy/Resource<I>>` implementation for `I`.
+- **Breaking** [client/server/commons] `AnonymousObject` was moved out of
+  `wayland-commons` into `wayland-client` and `wayland-server`. This is to accommodate the
+  design change above.
+- [scanner] Fixed a number of cases where invalid Rust code would be generated if variable
+  or method names in the protocol were Rust keywords.
 
 ## 0.21.11 -- 2019-01-19
 

wayland-client/src/lib.rs

@@ -3,76 +3,74 @@
 //! ## Overview
 //!
 //! This crate provides the interfaces and machinery to safely create
-//! client applications for the wayland protocol. It is a rust wrapper
+//! client applications for the Wayland protocol. It is a rust wrapper
 //! around the `libwayland-client.so` C library.
 //!
-//! The wayland protocol revolves around the creation of various objects
+//! The Wayland protocol revolves around the creation of various objects
 //! and the exchange of messages associated to these objects. The initial
 //! object is always the `Display`, that you get at initialization of the
 //! connection, exposed by this crate as `Display::connect_to_env()`.
 //!
 //! ## Protocol and messages handling model
 //!
 //! The protocol being bi-directional, you can send and receive messages.
-//! Sending messages is done via methods of `Proxy<_>` objects, receiving
-//! and handling them is done by providing implementations.
+//! Sending messages is done via methods of Rust objects corresponding to the wayland protocol
+//! objects, receiving and handling them is done by providing implementations.
 //!
 //! ### Proxies
 //!
-//! Wayland protocol objects are represented in this crate by `Proxy<I>`
-//! objects, where `I` is a type representing the interface of the considered
-//! object. And object's interface (think "class" in an object-oriented context)
-//! defines which messages it can send and receive.
+//! The underlying representation of Wayland protocol objects in this crate is `Proxy<I>`,
+//! where `I` is the type of the considered Rust object. An object's interface (think "class"
+//! in an object-oriented context) defines which messages it can send and receive.
 //!
-//! These proxies are used to send messages to the server (in the wayland context,
-//! these are called "requests"). To do so, you need to import the appropriate
-//! extension trait adding these methods. For example, to use a `Proxy<WlSurface>`,
-//! you need to import `protocol::wl_surface::RequestsTrait` from this crate.
+//! These proxies are used to send messages to the server (in the Wayland context,
+//! these are called "requests"). You usually don't use them directly, and instead call
+//! methods on the Rust objects themselves, which invoke the appropriate `Proxy` methods.
 //! It is also possible to directly use the `Proxy::<I>::send(..)` method, but
 //! this should only be done carefully: using it improperly can mess the protocol
 //! state and cause protocol errors, which are fatal to the connection (the server
 //! will kill you).
 //!
-//! There is not a 1 to 1 mapping between `Proxy<I>` instances and protocol
-//! objects. Rather, you can think of `Proxy<I>` as an `Rc`-like handle to a
-//! wayland object. Multiple instances of it can exist referring to the same
+//! There is not a 1 to 1 mapping between Rust object instances and protocol
+//! objects. Rather, you can think of the Rust objects as `Rc`-like handles to a
+//! Wayland object. Multiple instances of a Rust object can exist referring to the same
 //! protocol object.
 //!
-//! Similarly, the lifetimes of the protocol objects and the `Proxy<I>` are
+//! Similarly, the lifetimes of the protocol objects and the Rust objects are
 //! not tightly tied. As protocol objects are created and destroyed by protocol
 //! messages, it can happen that an object gets destroyed while one or more
-//! `Proxy<I>` still refers to it. In such case, these proxies will be disabled
-//! and their `alive()` method will start to return `false`. Trying to send messages
-//! with them will also fail.
+//! Rust objects still refer to it. In such case, these Rust objects will be disabled
+//! and the `alive()` method on the underlying `Proxy<I>` will start to return `false`.
+//! Trying to send messages with them will also fail.
 //!
 //! ### Implementations
 //!
-//! To receive and process messages from the server to you (in wayland context they are
-//! called "events"), you need to provide an `Implementation` for each wayland object
+//! To receive and process messages from the server to you (in Wayland context they are
+//! called "events"), 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 `NewProxy<I>` object. Providing an implementation via its `implement()` method
-//! will turn it into a regular `Proxy<I>` object.
+//! will turn it into a regular Rust object.
 //!
 //! **All objects must be implemented**, even if it is an implementation doing nothing.
 //! Failure to do so (by dropping the `NewProxy<I>` for example) can cause future fatal
 //! errors if the server tries to send an event to this object.
 //!
 //! An implementation is a struct implementing the `EventHandler` trait for the interface
-//! of the considered object. Alternatively, an `FnMut(I::Event, Proxy<I>)` closure can be
+//! of the considered object. Alternatively, an `FnMut(I::Event, I)` closure can be
 //! used with the `implement_closure()` method, where `I` is the interface
 //! of the considered object.
 //!
 //! ## Event Queues
 //!
-//! The wayland client machinery provides the possibility to have one or more event queues
-//! handling the processing of received messages. All wayland objects are associated to an
+//! The Wayland client machinery provides the possibility to have one or more event queues
+//! handling the processing of received messages. All Wayland objects are associated to an
 //! event queue, which controls when its events are dispatched.
 //!
 //! Events received from the server are stored in an internal buffer, and processed (by calling
 //! the appropriate implementations) when the associated event queue is dispatched.
 //!
 //! A default event queue is created at the same time as the initial `Display`, and by default
-//! whenever a wayland object is created, it inherits the queue of its parent (the object that sent
+//! whenever a Wayland object is created, it inherits the queue of its parent (the object that sent
 //! or receive the message that created the new object). It means that if you only plan to use the
 //! default event queue, you don't need to worry about assigning objects to their queues.
 //!
@@ -82,7 +80,7 @@
 //!
 //! ## Dynamic linking with `libwayland-client.so`
 //!
-//! If you need to gracefully handle the case of a system on which wayland is not installed (by
+//! If you need to gracefully handle the case of a system on which Wayland is not installed (by
 //! fallbacking to X11 for example), you can do so by activating the `dlopen` cargo feature.
 //!
 //! When this is done, the library will be loaded a runtime rather than directly linked. And trying
@@ -96,7 +94,7 @@
 //! - the `cursor` feature will try to load `libwayland-cursor.so`, a library helping with loading
 //!   system themed cursor textures, to integrate your app in the system theme.
 //! - the `egl` feature will try to load `libwayland-egl.so`, a library allowing the creation of
-//!   OpenGL surface from wayland surfaces.
+//!   OpenGL surface from Wayland surfaces.
 //!
 //! Both of them will also be loaded at runtime if the `dlopen` feature was provided. See their
 //! respective submodules for details about their use.

wayland-client/src/proxy.rs

@@ -21,9 +21,9 @@ use ProxyMap;
 /// tied to the lifetime of these handles, but rather to sending or
 /// receiving destroying messages.
 ///
-/// These handles are notably used to send requests to the server. To do
-/// you need to import the associated `RequestsTrait` trait from the module
-/// of this interface.
+/// These handles are notably used to send requests to the server. To do this
+/// you need to convert them to the corresponding Rust object (using `.into()`)
+/// and use methods on the Rust object.
 pub struct Proxy<I: Interface> {
     _i: ::std::marker::PhantomData<&'static I>,
     pub(crate) inner: ProxyInner,
@@ -58,7 +58,7 @@ impl<I: Interface> Proxy<I> {
     ///
     /// **Warning:** This method is mostly intended to be used by code generated
     /// by `wayland-scanner`, and you should probably never need to use it directly,
-    /// but rather use the appropriate `RequestsTrait` for your proxy.
+    /// but rather use the appropriate methods on the Rust object.
     ///
     /// This is the generic method to send requests.
     ///
@@ -71,7 +71,7 @@ impl<I: Interface> Proxy<I> {
     ///
     /// **Warning:** This method is mostly intended to be used by code generated
     /// by `wayland-scanner`, and you should probably never need to use it directly,
-    /// but rather use the appropriate `RequestsTrait` for your proxy.
+    /// but rather use the appropriate methods on the Rust object.
     ///
     /// This is the generic method to send requests that create objects
     ///
@@ -139,7 +139,7 @@ impl<I: Interface> Proxy<I> {
     ///
     /// **Warning:** This method is mostly intended to be used by code generated
     /// by `wayland-scanner`, and you should probably never need to use it directly,
-    /// but rather use the appropriate `RequestsTrait` for your proxy.
+    /// but rather use the appropriate methods on the Rust object.
     ///
     /// This creates a new wayland object, considered as a
     /// child of this object. It will notably inherit its interface
@@ -191,7 +191,7 @@ impl<I: Interface> Proxy<I> {
     ///
     /// **Warning:** This method is mostly intended to be used by code generated
     /// by `wayland-scanner`, and you should probably never need to use it directly,
-    /// but rather use the appropriate `RequestsTrait` for your proxy.
+    /// but rather use the appropriate methods on the Rust object.
     pub fn child_placeholder<J: Interface + From<Proxy<J>>>(&self) -> J {
         Proxy::wrap(self.inner.child_placeholder()).into()
     }
@@ -263,7 +263,7 @@ impl Proxy<::protocol::wl_display::WlDisplay> {
 /// receive it as a `NewProxy`. You then have to provide an
 /// implementation for it, in order to process the incoming
 /// events it may receive. Once this done you will be able
-/// to use it as a regular `Proxy`.
+/// to use it as a regular Rust object.
 ///
 /// Implementations are structs implementing the appropriate
 /// variant of the `Implementation` trait. They can also be

wayland-server/src/lib.rs

@@ -3,67 +3,71 @@
 //! ## Overview
 //!
 //! This crate provides the interfaces and machinery to safely create servers
-//! for the wayland protocol. It is a rust wrapper around the `libwayland-server.so`
+//! 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
+//! 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.
+//! The protocol being bi-directional, you can send and receive messages.
+//! Sending messages is done via methods of Rust objects corresponding to the wayland protocol
+//! 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 send 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 tightly 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.
+//! main difference being that the underlying handles to objects are represented by the `Resource<I>`
+//! type, very similarly to proxies in `wayland-client`.
+//!
+//! These resources are used to send messages to the client (in the Wayland context,
+//! these are called "events"). You usually don't use them directly, and instead call
+//! methods on the Rust objects themselves, which invoke the appropriate `Resource` methods.
+//! It is also possible to directly use the `Resource::<I>::send(..)` method.
+//!
+//! There is not a 1 to 1 mapping between Rust object instances and protocol
+//! objects. Rather, you can think of the Rust objects as `Rc`-like handles to a
+//! Wayland object. Multiple instances of a Rust object can exist referring to the same
+//! protocol object.
+//!
+//! Similarly, the lifetimes of the protocol objects and the Rust objects are
+//! not tightly tied. As protocol objects are created and destroyed by protocol
+//! messages, it can happen that an object gets destroyed while one or more
+//! Rust objects still refer to it. In such case, these Rust objects will be disabled
+//! and the `alive()` method on the underlying `Resource<I>` 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
+//! 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.
+//! will turn it into a regular Rust 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 a struct implementing the `RequestHandler` trait for the interface
-//! of the considered object. Alternatively, an `FnMut(I::Request, Resource<I>)` closure can be
+//! of the considered object. Alternatively, an `FnMut(I::Request, I)` closure can be
 //! used with the `implement_closure()` method, where `I` is the interface
 //! of the considered object.
 //!
-//! The `Resource<I>` passed to your implementation is guaranteed to be alive (as it just received
+//! A Rust object passed to your implementation is guaranteed 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
+//! 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).
 //!
-//! To properly function, this wayland implementation also needs an event loop structure,
+//! To properly function, this Wayland implementation also needs an event loop structure,
 //! which is here provided by the `calloop` crate. It is a public dependency and is reexported
 //! as `wayland_server::calloop`.
 

wayland-server/src/resource.rs

@@ -18,7 +18,9 @@ use imp::{NewResourceInner, ResourceInner};
 /// receiving destroying messages.
 ///
 /// These handles are notably used to send events to the associated client,
-/// via the `send` method.
+/// via the `send` method, although you're encouraged to use methods on the
+/// corresponding Rust objects instead. To convert a `Resource<I>` into the
+/// `I` Rust object, use the `.into()` method.
 pub struct Resource<I: Interface> {
     _i: ::std::marker::PhantomData<&'static I>,
     inner: ResourceInner,
@@ -168,7 +170,7 @@ impl<I: Interface> Resource<I> {
 /// receive it as a `NewResource`. You then have to provide an
 /// implementation for it, in order to process the incoming
 /// events it may receive. Once this done you will be able
-/// to use it as a regular `Resource`.
+/// to use it as a regular Rust object.
 ///
 /// Implementations are structs implementing the appropriate
 /// variant of the `Implementation` trait. They can also be