Document how style traits can be derived

4 files changed, 44 insertions, 3 deletions

diff --git a/components/style/values/animated/mod.rs b/components/style/values/animated/mod.rs
index 71f6e2bd4db..c2d42192fdd 100644
--- a/components/style/values/animated/mod.rs
+++ b/components/style/values/animated/mod.rs
@@ -28,7 +28,19 @@ use values::specified::url::SpecifiedUrl;
 pub mod color;
 pub mod effects;
 
-/// Animating from one value to another.
+/// Animate from one value to another.
+///
+/// This trait is derivable with `#[derive(Animate)]`. The derived
+/// implementation uses a `match` expression with identical patterns for both
+/// `self` and `other`, calling `Animate::animate` on each fields of the values.
+/// If a field is annotated with `#[animation(constant)]`, the two values should
+/// be equal or an error is returned.
+///
+/// If a variant is annotated with `#[animation(error)]`, the corresponding
+/// `match` arm is not generated.
+///
+/// If the two values are not similar, an error is returned unless a fallback
+/// function has been specified through `#[animate(fallback)]`.
 pub trait Animate: Sized {
     /// Animate a value towards another one, given an animation procedure.
     fn animate(&self, other: &Self, procedure: Procedure) -> Result<Self, ()>;
@@ -51,6 +63,8 @@ pub enum Procedure {
 /// Conversion between computed values and intermediate values for animations.
 ///
 /// Notably, colors are represented as four floats during animations.
+///
+/// This trait is derivable with `#[derive(ToAnimatedValue)]`.
 pub trait ToAnimatedValue {
     /// The type of the animated value.
     type AnimatedValue;
@@ -66,6 +80,13 @@ pub trait ToAnimatedValue {
 pub trait AnimatedValueAsComputed {}
 
 /// Returns a value similar to `self` that represents zero.
+///
+/// This trait is derivable with `#[derive(ToAnimatedValue)]`. If a field is
+/// annotated with `#[animation(constant)]`, a clone of its value will be used
+/// instead of calling `ToAnimatedZero::to_animated_zero` on it.
+///
+/// If a variant is annotated with `#[animation(error)]`, the corresponding
+/// `match` arm is not generated.
 pub trait ToAnimatedZero: Sized {
     /// Returns a value that, when added with an underlying value, will produce the underlying
     /// value. This is used for SMIL animation's "by-animation" where SMIL first interpolates from
diff --git a/components/style/values/computed/mod.rs b/components/style/values/computed/mod.rs
index f3d6c5d658d..3bb03d861de 100644
--- a/components/style/values/computed/mod.rs
+++ b/components/style/values/computed/mod.rs
@@ -199,6 +199,11 @@ impl<'a, 'cx, 'cx_a: 'cx, S: ToComputedValue + 'a> Iterator for ComputedVecIter<
 }
 
 /// A trait to represent the conversion between computed and specified values.
+///
+/// This trait is derivable with `#[derive(ToComputedValue)]`. The derived
+/// implementation just calls `ToComputedValue::to_computed_value` on each field
+/// of the passed value, or `Clone::clone` if the field is annotated with
+/// `#[compute(clone)]`.
 pub trait ToComputedValue {
     /// The computed value type we're going to be converted to.
     type ComputedValue;
diff --git a/components/style/values/distance.rs b/components/style/values/distance.rs
index d4eb91f112f..351f1eb021f 100644
--- a/components/style/values/distance.rs
+++ b/components/style/values/distance.rs
@@ -10,6 +10,17 @@ use std::iter::Sum;
 use std::ops::Add;
 
 /// A trait to compute squared distances between two animatable values.
+///
+/// This trait is derivable with `#[derive(ComputeSquaredDistance)]`. The derived
+/// implementation uses a `match` expression with identical patterns for both
+/// `self` and `other`, calling `ComputeSquaredDistance::compute_squared_distance`
+/// on each fields of the values.
+///
+/// If a variant is annotated with `#[animation(error)]`, the corresponding
+/// `match` arm is not generated.
+///
+/// If the two values are not similar, an error is returned unless a fallback
+/// function has been specified through `#[distance(fallback)]`.
 pub trait ComputeSquaredDistance {
     /// Computes the squared distance between two animatable values.
     fn compute_squared_distance(&self, other: &Self) -> Result<SquaredDistance, ()>;
diff --git a/components/style_traits/values.rs b/components/style_traits/values.rs
index 5e4c093fd73..94e59e26bbe 100644
--- a/components/style_traits/values.rs
+++ b/components/style_traits/values.rs
@@ -18,8 +18,12 @@ use std::fmt::{self, Write};
 ///   of their name;
 /// * unit variants whose name starts with "Moz" or "Webkit" are prepended
 ///   with a "-";
-/// * variants with fields get serialised as the space-separated serialisations
-///   of their fields.
+/// * if `#[css(comma)]` is found on a variant, its fields are separated by
+///   commas, otherwise, by spaces;
+/// * if `#[css(function)]` is found on a variant, the variant name gets
+///   serialised like unit variants and its fields are surrounded by parentheses;
+/// * finally, one can put `#[css(derive_debug)]` on the whole type, to
+///   implement `Debug` by a single call to `ToCss::to_css`.
 pub trait ToCss {
     /// Serialize `self` in CSS syntax, writing to `dest`.
     fn to_css<W>(&self, dest: &mut W) -> fmt::Result where W: Write;