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/common.rs

@@ -112,12 +112,15 @@ pub fn build_bar_config(j: &json::Value) -> reply::BarConfig {
                     "separator" => reply::ColorableBarPart::Separator,
 
                     #[cfg(feature = "i3-4-12")]
+                    #[doc(cfg(feature = "i3-4-12"))]
                     "focused_background" => reply::ColorableBarPart::FocusedBackground,
 
                     #[cfg(feature = "i3-4-12")]
+                    #[doc(cfg(feature = "i3-4-12"))]
                     "focused_statusline" => reply::ColorableBarPart::FocusedStatusline,
 
                     #[cfg(feature = "i3-4-12")]
+                    #[doc(cfg(feature = "i3-4-12"))]
                     "focused_separator" => reply::ColorableBarPart::FocusedSeparator,
 
                     "focused_workspace_text" => reply::ColorableBarPart::FocusedWorkspaceText,

src/event.rs

@@ -18,6 +18,7 @@ pub enum Event {
     BindingEvent(BindingEventInfo),
 
     #[cfg(feature = "i3-4-14")]
+    #[doc(cfg(feature = "i3-4-14"))]
     ShutdownEvent(ShutdownEventInfo),
 }
 
@@ -136,6 +137,7 @@ impl FromStr for WindowEventInfo {
                 "urgent" => WindowChange::Urgent,
 
                 #[cfg(feature = "i3-4-13")]
+                #[doc(cfg(feature = "i3-4-13"))]
                 "mark" => WindowChange::Mark,
 
                 other => {
@@ -217,11 +219,13 @@ impl FromStr for BindingEventInfo {
 /// Data for `ShutdownEvent`.
 #[derive(Debug)]
 #[cfg(feature = "i3-4-14")]
+#[doc(cfg(feature = "i3-4-14"))]
 pub struct ShutdownEventInfo {
     pub change: ShutdownChange,
 }
 
 #[cfg(feature = "i3-4-14")]
+#[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 +289,7 @@ pub mod inner {
 
         /// A mark has been added to or removed from the window.
         #[cfg(feature = "i3-4-13")]
+        #[doc(cfg(feature = "i3-4-13"))]
         Mark,
 
         /// A WindowChange we don't support yet.
@@ -333,6 +338,7 @@ pub mod inner {
     /// The kind of shutdown change.
     #[derive(Debug)]
     #[cfg(feature = "i3-4-14")]
+    #[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]
@@ -180,6 +182,7 @@ impl<'a> Iterator for EventIterator<'a> {
                 5 => event::Event::BindingEvent(try!(event::BindingEventInfo::from_str(payload))),
 
                 #[cfg(feature = "i3-4-14")]
+                #[doc(cfg(feature = "i3-4-14"))]
                 6 => event::Event::ShutdownEvent(try!(event::ShutdownEventInfo::from_str(payload))),
 
                 _ => unreachable!("received an event we aren't subscribed to!")
@@ -211,6 +214,7 @@ pub enum Subscription {
     BarConfig,
     Binding,
     #[cfg(feature = "i3-4-14")]
+    #[doc(cfg(feature = "i3-4-14"))]
     Shutdown,
 }
 
@@ -247,6 +251,7 @@ impl I3EventListener {
                         Subscription::BarConfig => "\"barconfig_update\"",
                         Subscription::Binding => "\"binding\"",
                         #[cfg(feature = "i3-4-14")]
+                        #[doc(cfg(feature = "i3-4-14"))]
                         Subscription::Shutdown => "\"shutdown\""})
                     .collect::<Vec<_>>()
                     .join(", ")[..]
@@ -478,6 +483,7 @@ impl I3Connection {
 
     /// Gets the list of currently configured binding modes.
     #[cfg(feature = "i3-4-13")]
+    #[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")]
+    #[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")]
+    #[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")]
+    #[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")]
+#[doc(cfg(feature = "i3-4-13"))]
 #[derive(Debug)]
 pub struct BindingModes {
     /// A vector of all currently configured binding modes.