Improve documentation of feature flags

x11rb has some explanation of its feature flags on its main
documentation page. This commit improves this to explicitly say which
"X11 extensions that are needed internally" are always enabled.
Additionally, some unnecessary "crate::" at the beginning of links is
removed.

Then, a similar documentation is added to x11rb-protocol and
x11rb-async.

Signed-off-by: Uli Schlachter <[email protected]>

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.
 //!
 //! # Integrating x11rb with an Event Loop