Finalize the structure of wayland-sys.

And add some dcumentation.

wayland-client/Cargo.toml

@@ -13,7 +13,7 @@ crossbeam = "0.1.5"
 dlib = "0.1"
 libc = "0.1"
 lazy_static = { version = "0.1", optional = true }
-wayland-sys = { path = "../wayland-sys" }
+wayland-sys = { path = "../wayland-sys", features = ["client"] }
 
 [build-dependencies.wayland-rust-scanner]
 path = "../scanner"

wayland-sys/Cargo.toml

@@ -10,4 +10,5 @@ lazy_static = { version = "0.1", optional = true }
 
 [features]
 dlopen = ["dlib/dlopen", "lazy_static"]
+client = []
 egl = []

wayland-sys/src/client.rs

@@ -1,3 +1,7 @@
+//! Bindings to the client library `libwayland-client.so`
+//!
+//! The generated handle is named `WAYLAND_CLIENT_HANDLE`
+
 use libc::{c_char, c_void, c_int, size_t, uint32_t};
 
 use super::common::*;

wayland-sys/src/common.rs

@@ -1,3 +1,6 @@
+//! Various types and functions that are used by both the client and the server
+//! libraries.
+
 use libc::{c_char, c_void, c_int, size_t};
 
 #[repr(C)]

wayland-sys/src/egl.rs

@@ -1,3 +1,9 @@
+//! Bindings to the EGL library `libwayland-egl.so`
+//!
+//! This lib allows to create EGL surfaces out of wayland surfaces.
+//!
+//! The created handle is named `WAYLAND_EGl_HANDLE`.
+
 use libc::c_int;
 use client::wl_proxy;
 

wayland-sys/src/lib.rs

@@ -1,6 +1,38 @@
 #![allow(dead_code, non_camel_case_types)]
 
-#[macro_use]
+//! FFI bindings to the wayland system libraries.
+//!
+//! The names exported by this crate should *not* be used directly, but though
+//! the `ffi_dispatch` macro like this:
+//!
+//! ```ignore
+//! ffi_dispatch!(HANDLE_NAME, func_name, arg1, arg2, arg3);
+//! ```
+//!
+//! Where `HANDLE_NAME` is the name of the handle generated if the cargo feature
+//! `dlopen` is on.
+//!
+//! For this to work, you must ensure every needed symbol is in scope (aka the static handle
+//! if `dlopen` is on, the extern function if not). The easiest way to do this is to glob import
+//! the appropriate module. For example:
+//!
+//! ```
+//! #[macro_use] extern crate wayland_sys;
+//!
+//! use wayland_sys::client::*;
+//!
+//! fn main() {
+//!     let display_ptr = unsafe {
+//!         ffi_dispatch!(WAYLAND_CLIENT_HANDLE, wl_display_connect, ::std::ptr::null())
+//!     };
+//! }
+//! ```
+//!
+//! Each module except `common` corresponds to a system library. They all define a function named
+//! `is_lib_available()` which returns a boolean depending on whether the lib could be loaded.
+//! They always return true if the feature `dlopen` is absent, as the lib is then directly linked.
+
+#[macro_use(external_library,link_external_library,dlopen_external_library)]
 extern crate dlib;
 
 #[cfg(feature = "dlopen")]
@@ -10,7 +42,25 @@ extern crate lazy_static;
 extern crate libc;
 
 pub mod common;
+
+#[cfg(feature = "client")]
 pub mod client;
 
 #[cfg(feature = "egl")]
-pub mod egl;
+pub mod egl;
+
+#[cfg(feature = "dlopen")]
+#[macro_export]
+macro_rules! ffi_dispatch(
+    ($handle: ident, $func: ident, $($arg: expr),*) => (
+        ($handle.$func)($($arg),*)
+    )
+);
+
+#[cfg(not(feature = "dlopen"))]
+#[macro_export]
+macro_rules! ffi_dispatch(
+    ($handle: ident, $func: ident, $($arg: expr),*) => (
+        $func($($arg),*)
+    )
+);