Update docs for conditional compilation

- Update README to explain the versioning
- Add attributes that make conditional features stand out in the
  generated rustdocs. This relies on an experimental `doc_cfg` compiler
  feature which doesn't exist on stable, so opt into it with a `dox`
  feature in i3ipc-rs that can be enabled for documentation builds.

Author: tmerr

Cargo.toml

@@ -16,3 +16,5 @@ serde_json = "0.6.0"
 i3-4-12 = []
 i3-4-13 = ["i3-4-12"]
 i3-4-14 = ["i3-4-13"]
+i3-next = ["i3-4-14"]
+dox = ["i3-next"]

README.md

@@ -10,8 +10,8 @@ A Rust library for controlling i3-wm through its [IPC interface](https://i3wm.or
 ## Usage
 Add this to your Cargo.toml
 ```toml
-[dependencies]
-i3ipc = "0.7.0"
+[dependencies.i3ipc]
+version = "0.7.0"
 ```
 
 ## Messages:
@@ -59,8 +59,14 @@ fn main() {
 }
 ```
 
-## Compatibility
+## Versioning
 
-This library was last updated for **i3 version 4.11**, but is forward compatible. Contributions are welcome!
+By default i3ipc-rs targets minimum i3 version 4.11. To unlock additional features you can increase this by selecting one of `"i3-4-12"`, ..., `"i3-4-14"` in Cargo.toml.
 
-All documented functionality from i3 version 4.11 can be handled by this library. Additions to the i3 IPC interface that are not understood by this library will generally return an `Unknown` value and log a warning to the target `"i3ipc"` using the [log crate](http://doc.rust-lang.org/log). Binaries using this library should [install a logger](https://doc.rust-lang.org/log/log/index.html#in-executables) to view details of such additions.
+```
+[dependencies.i3ipc]
+version = "0.7.0"
+features = ["i3-4-14"]
+```
+
+Additions to the i3 IPC interface that are not understood by your compiled binary will generally return an `Unknown` value and log a warning to the target `"i3ipc"` using the [log crate](http://doc.rust-lang.org/log). Binaries using this library should [install a logger](https://doc.rust-lang.org/log/log/index.html#in-executables) to view details of such additions.

src/event.rs

@@ -18,6 +18,7 @@ pub enum Event {
     BindingEvent(BindingEventInfo),
 
     #[cfg(feature = "i3-4-14")]
+    #[cfg_attr(feature = "dox", doc(cfg(feature = "i3-4-14")))]
     ShutdownEvent(ShutdownEventInfo),
 }
 
@@ -217,11 +218,13 @@ impl FromStr for BindingEventInfo {
 /// Data for `ShutdownEvent`.
 #[derive(Debug)]
 #[cfg(feature = "i3-4-14")]
+#[cfg_attr(feature = "dox", doc(cfg(feature = "i3-4-14")))]
 pub struct ShutdownEventInfo {
     pub change: ShutdownChange,
 }
 
 #[cfg(feature = "i3-4-14")]
+#[cfg_attr(feature = "dox", doc(cfg(feature = "i3-4-14")))]
 impl FromStr for ShutdownEventInfo {
     type Err = json::error::Error;
     fn from_str(s: &str) -> Result<Self, Self::Err> {
@@ -285,6 +288,7 @@ pub mod inner {
 
         /// A mark has been added to or removed from the window.
         #[cfg(feature = "i3-4-13")]
+        #[cfg_attr(feature = "dox", doc(cfg(feature = "i3-4-13")))]
         Mark,
 
         /// A WindowChange we don't support yet.
@@ -333,6 +337,7 @@ pub mod inner {
     /// The kind of shutdown change.
     #[derive(Debug)]
     #[cfg(feature = "i3-4-14")]
+    #[cfg_attr(feature = "dox", doc(cfg(feature = "i3-4-14")))]
     pub enum ShutdownChange {
         Restart,
         Exit,

src/lib.rs

@@ -15,6 +15,8 @@
 //! This library should cover all of i3's documented ipc features. If it's missing something
 //! please open an issue on github.
 
+#![cfg_attr(feature = "dox", feature(doc_cfg))]
+
 extern crate unix_socket;
 extern crate byteorder;
 #[macro_use]
@@ -211,6 +213,7 @@ pub enum Subscription {
     BarConfig,
     Binding,
     #[cfg(feature = "i3-4-14")]
+    #[cfg_attr(feature = "dox", doc(cfg(feature = "i3-4-14")))]
     Shutdown,
 }
 
@@ -478,6 +481,7 @@ impl I3Connection {
 
     /// Gets the list of currently configured binding modes.
     #[cfg(feature = "i3-4-13")]
+    #[cfg_attr(feature = "dox", doc(cfg(feature = "i3-4-13")))]
     pub fn get_binding_modes(&mut self) -> Result<reply::BindingModes, MessageError> {
         if let Err(e) = self.stream.send_i3_message(8, "") {
             return Err(MessageError::Send(e));

src/reply.rs

@@ -221,16 +221,19 @@ pub enum ColorableBarPart {
 
     /// Background color of the bar on the currently focused monitor output.
     #[cfg(feature = "i3-4-12")]
+    #[cfg_attr(feature = "dox", doc(cfg(feature = "i3-4-12")))]
     FocusedBackground,
 
     /// Text color to be used for the statusline on the currently focused
     /// monitor output.
     #[cfg(feature = "i3-4-12")]
+    #[cfg_attr(feature = "dox", doc(cfg(feature = "i3-4-12")))]
     FocusedStatusline,
 
     /// Text color to be used for the separator on the currently focused
     /// monitor output.
     #[cfg(feature = "i3-4-12")]
+    #[cfg_attr(feature = "dox", doc(cfg(feature = "i3-4-12")))]
     FocusedSeparator,
 
     /// Text color for a workspace button when the workspace has focus.
@@ -357,6 +360,7 @@ pub struct Version {
 
 /// The reply to the `get_binding_modes` request.
 #[cfg(feature = "i3-4-13")]
+#[cfg_attr(feature = "dox", doc(cfg(feature = "i3-4-13")))]
 #[derive(Debug)]
 pub struct BindingModes {
     /// A vector of all currently configured binding modes.