Merge pull request #887 from psychon/flag-docs

Improve documentation of feature flags

x11rb-async/src/lib.rs

@@ -1,6 +1,43 @@
 // This code is dual licensed under MIT OR Apache 2.0.
 
 //! Asynchronous X11 rust bindings.
+//!
+//! This library allows to interact with an X11 server from rust code. A connection to an X11
+//! server is represented by an implementation of the `Connection` trait.
+//!
+//! The client can interact with the server by sending requests. The server can answer requests and
+//! can also generate events.
+//!
+//! The examples that come with this library might be a good starting point for new users.
+//!
+//!
+//! # Feature flags
+//!
+//! This crate uses [feature
+//! flags](https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section) to reduce
+//! the amount of compiled code. There are two kinds of feature flags available:
+//!
+//! * Feature flags for specific X11 extensions
+//! * Feature flags for additional functionality
+//!
+//! ## Feature flags for specific X11 extensions
+//!
+//! By default, only the core X11 protocol and X11 extensions that are needed internally are
+//! enabled. These are the `bigreq`, `ge` and `xc_misc` extensions. Further extensions need to be
+//! explicitly enabled via their feature flag:
+//!
+//! `composite`, `damage`, `dpms`, `dri2`, `dri3`, `glx`, `present`, `randr`, `record`, `render`,
+//! `res`, `screensaver`, `shape`, `shm`, `sync`, `xevie`, `xf86dri`, `xf86vidmode`, `xfixes`,
+//! `xinerama`, `xinput`, `xkb`, `xprint`, `xselinux`, `xtest`, `xv`, `xvmc`.
+//!
+//! If you want to take the "I do not want to think about this"-approach, you can enable the
+//! `all-extensions` feature to just enable, well, all extensions.
+//!
+//! ## Feature flags for additional functionality
+//!
+//! Additionally, the following flags exist:
+//! * `allow-unsafe-code`: Enable the same feature in x11rb and implement
+//! [`blocking::BlockingConnection`] for [`x11rb::xcb_ffi::XCBConnection`]
 
 // -- Public Modules --
 

x11rb-protocol/src/lib.rs

@@ -5,6 +5,37 @@
 //!
 //! This protocol does not do any I/O. If you need an X11 client library, look at
 //! <https://docs.rs/x11rb/latest/x11rb/>.
+//!
+//! # Feature flags
+//!
+//! This crate uses [feature
+//! flags](https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section) to reduce
+//! the amount of compiled code. There are two kinds of feature flags available:
+//!
+//! * Feature flags for specific X11 extensions
+//! * Feature flags for additional functionality
+//!
+//! ## Feature flags for specific X11 extensions
+//!
+//! By default, only the core X11 protocol and some small, commonly needed X11 extensions are
+//! enabled. These are the `bigreq`, `ge` and `xc_misc` extensions. Further extensions need to be
+//! explicitly enabled via their feature flag:
+//!
+//! `composite`, `damage`, `dpms`, `dri2`, `dri3`, `glx`, `present`, `randr`, `record`, `render`,
+//! `res`, `screensaver`, `shape`, `shm`, `sync`, `xevie`, `xf86dri`, `xf86vidmode`, `xfixes`,
+//! `xinerama`, `xinput`, `xkb`, `xprint`, `xselinux`, `xtest`, `xv`, `xvmc`.
+//!
+//! If you want to take the "I do not want to think about this"-approach, you can enable the
+//! `all-extensions` feature to just enable, well, all extensions.
+//!
+//! ## Feature flags for additional functionality
+//!
+//! Additionally, the following flags exist:
+//! * `std` (enabled by default): Enable functionality needing the std library, e.g. environment
+//!   variables or [`std::os::unix::io::OwnedFd`].
+//! * `resource_manager`: Enable the code in [resource_manager] for loading and querying the
+//!   X11 resource database.
+//! * `serde`: Implement [`serde::Serialize`] and [`serde::Deserialize`] for all objects.
 
 #![forbid(
     missing_copy_implementations,

x11rb/src/lib.rs

@@ -84,9 +84,9 @@
 //!
 //! ### Feature flags for specific X11 extensions
 //!
-//! By default, only the core X11 protocol and X11 extensions that are
-//! needed internally are enabled. Further extensions need to be explicitly enabled via their
-//! feature flag:
+//! By default, only the core X11 protocol and X11 extensions that are needed internally are
+//! enabled. These are the `bigreq`, `ge` and `xc_misc` extensions. Further extensions need to be
+//! explicitly enabled via their feature flag:
 //!
 //! `composite`, `damage`, `dpms`, `dri2`, `dri3`, `glx`, `present`, `randr`, `record`, `render`,
 //! `res`, `screensaver`, `shape`, `shm`, `sync`, `xevie`, `xf86dri`, `xf86vidmode`, `xfixes`,
@@ -99,14 +99,14 @@
 //!
 //! Additionally, the following flags exist:
 //! * `allow-unsafe-code`: Enable features that require `unsafe`. Without this flag,
-//!   `x11rb::xcb_ffi::XCBConnection` and some support code for it are unavailable.
-//! * `cursor`: Enable the code in [crate::cursor] for loading cursor files.
-//! * `resource_manager`: Enable the code in [crate::resource_manager] for loading and querying the
+//!   [`xcb_ffi::XCBConnection`] and some support code for it are unavailable.
+//! * `cursor`: Enable the code in [cursor] for loading cursor files.
+//! * `resource_manager`: Enable the code in [resource_manager] for loading and querying the
 //!   X11 resource database.
-//! * `image`: Enable the code in [crate::image] for working with pixel image data.
+//! * `image`: Enable the code in [image] for working with pixel image data.
 //! * `dl-libxcb`: Enabling this feature will prevent from libxcb being linked to the
 //!   resulting executable. Instead libxcb will be dynamically loaded at runtime.
-//!   This feature adds the [`crate::xcb_ffi::load_libxcb`] function, that allows to load
+//!   This feature adds the [`xcb_ffi::load_libxcb`] function, that allows to load
 //!   libxcb and check for success or failure.
 //! * `extra-traits`: Enable some additional traits for generated code, like `Eq`, `Ord` and
 //!   `Hash`. This is not needed by default and adds a large amount of code that bloats codegen