Document the cargo cfgs

serde/Cargo.toml

@@ -16,21 +16,55 @@ publish = false # this branch contains breaking changes
 [badges]
 travis-ci = { repository = "serde-rs/serde" }
 
-[features]
-default = ["std"]
-derive = ["serde_derive"]
-
-std = []
-unstable = []
-alloc = ["unstable"]
-collections = ["alloc"]
-unstable-testing = ["unstable", "std"]
-
-# to get serde_derive picked up by play.integer32.com
-playground = ["serde_derive"]
-
 [dependencies]
 serde_derive = { version = "0.9", optional = true, path = "../serde_derive" }
 
 [dev-dependencies]
 serde_derive = { version = "0.9", path = "../serde_derive" }
+
+
+### FEATURES #################################################################
+
+[features]
+default = ["std"]
+
+# Re-export the derive(Serialize, Deserialize) macros. This is specifically
+# intended for library crates that provide optional Serde impls behind a Cargo
+# cfg of their own. All other crates should depend on serde_derive directly.
+#
+# Please refer to the long comment above the line `pub use serde_derive::*` in
+# src/lib.rs before enabling this feature. If you think you need this feature
+# and your use case does not precisely match the one described in the comment,
+# please open an issue to let us know about your use case.
+derive = ["serde_derive"]
+
+# Provide impls for common standard library types like Vec<T> and HashMap<K, V>.
+# Requires a dependency on the Rust standard library.
+std = []
+
+# Provide impls for types that require unstable functionality. For tracking and
+# discussion of unstable functionality please refer to this issue:
+#
+#    https://github.com/serde-rs/serde/issues/812
+unstable = []
+
+# Provide impls for types that require memory allocation like Box<T> and Rc<T>.
+# This is a subset of std but may be enabled without depending on all of std.
+#
+# Requires a dependency on the unstable core allocation library:
+#
+#    https://doc.rust-lang.org/alloc/
+alloc = ["unstable"]
+
+# Provide impls for collection types like String and Cow<T>. This is a subset of
+# std but may be enabled without depending on all of std.
+#
+# Requires a dependency on the unstable collections library:
+#
+#    https://doc.rust-lang.org/collections/
+collections = ["alloc"]
+
+# Get serde_derive picked up by the Integer 32 playground. Not public API.
+#
+#    http://play.integer32.com/
+playground = ["serde_derive"]

travis.sh

@@ -29,10 +29,10 @@ if [ -n "${CLIPPY}" ]; then
     fi
 
     cd "$DIR/serde"
-    cargo clippy --features unstable-testing -- -Dclippy
+    cargo clippy --features unstable -- -Dclippy
 
     cd "$DIR/serde_derive"
-    cargo clippy --features unstable-testing -- -Dclippy
+    cargo clippy --features unstable -- -Dclippy
 
     cd "$DIR/test_suite"
     cargo clippy --features unstable -- -Dclippy
@@ -47,7 +47,7 @@ else
     channel build --no-default-features
     channel build --no-default-features --features alloc
     channel build --no-default-features --features collections
-    channel test --features unstable-testing
+    channel test --features unstable
     cd "$DIR/test_suite/deps"
     channel build
     cd "$DIR/test_suite"