Add some documentation to the style crate.

components/style/animation.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! CSS transitions and animations.
+
 use app_units::Au;
 use bezier::Bezier;
 use cssparser::{Color, RGBA};
@@ -393,6 +395,9 @@ impl AnimatedProperty {
     }
 }
 
+/// A trait used to implement [interpolation][interpolated-types].
+///
+/// [interpolated-types]: https://drafts.csswg.org/css-transitions/#interpolated-types
 trait Interpolate: Sized {
     fn interpolate(&self, other: &Self, time: f64) -> Option<Self>;
 }
@@ -418,6 +423,7 @@ impl <T> Interpolate for Option<T> where T: Interpolate {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-number
 impl Interpolate for f32 {
     #[inline]
     fn interpolate(&self, other: &f32, time: f64) -> Option<f32> {
@@ -425,6 +431,7 @@ impl Interpolate for f32 {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-number
 impl Interpolate for f64 {
     #[inline]
     fn interpolate(&self, other: &f64, time: f64) -> Option<f64> {
@@ -432,6 +439,7 @@ impl Interpolate for f64 {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-integer
 impl Interpolate for i32 {
     #[inline]
     fn interpolate(&self, other: &i32, time: f64) -> Option<i32> {
@@ -448,6 +456,7 @@ impl Interpolate for Angle {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-visibility
 impl Interpolate for Visibility {
     #[inline]
     fn interpolate(&self, other: &Visibility, time: f64)
@@ -467,6 +476,7 @@ impl Interpolate for Visibility {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-integer
 impl Interpolate for ZIndex {
     #[inline]
     fn interpolate(&self, other: &ZIndex, time: f64)
@@ -483,6 +493,7 @@ impl Interpolate for ZIndex {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-length
 impl Interpolate for VerticalAlign {
     #[inline]
     fn interpolate(&self, other: &VerticalAlign, time: f64)
@@ -499,6 +510,7 @@ impl Interpolate for VerticalAlign {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-simple-list
 impl Interpolate for BorderSpacing {
     #[inline]
     fn interpolate(&self, other: &BorderSpacing, time: f64)
@@ -511,6 +523,7 @@ impl Interpolate for BorderSpacing {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-color
 impl Interpolate for RGBA {
     #[inline]
     fn interpolate(&self, other: &RGBA, time: f64) -> Option<RGBA> {
@@ -526,6 +539,7 @@ impl Interpolate for RGBA {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-color
 impl Interpolate for Color {
     #[inline]
     fn interpolate(&self, other: &Color, time: f64) -> Option<Color> {
@@ -540,6 +554,7 @@ impl Interpolate for Color {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-lpcalc
 impl Interpolate for CalcLengthOrPercentage {
     #[inline]
     fn interpolate(&self, other: &CalcLengthOrPercentage, time: f64)
@@ -551,6 +566,7 @@ impl Interpolate for CalcLengthOrPercentage {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-lpcalc
 impl Interpolate for LengthOrPercentage {
     #[inline]
     fn interpolate(&self, other: &LengthOrPercentage, time: f64)
@@ -579,6 +595,7 @@ impl Interpolate for LengthOrPercentage {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-lpcalc
 impl Interpolate for LengthOrPercentageOrAuto {
     #[inline]
     fn interpolate(&self, other: &LengthOrPercentageOrAuto, time: f64)
@@ -610,6 +627,7 @@ impl Interpolate for LengthOrPercentageOrAuto {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-lpcalc
 impl Interpolate for LengthOrPercentageOrNone {
     #[inline]
     fn interpolate(&self, other: &LengthOrPercentageOrNone, time: f64)
@@ -635,6 +653,8 @@ impl Interpolate for LengthOrPercentageOrNone {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-number
+/// https://drafts.csswg.org/css-transitions/#animtype-length
 impl Interpolate for LineHeight {
     #[inline]
     fn interpolate(&self, other: &LineHeight, time: f64)
@@ -660,7 +680,7 @@ impl Interpolate for LineHeight {
     }
 }
 
-/// http://dev.w3.org/csswg/css-transitions/#animtype-font-weight
+/// https://drafts.csswg.org/css-transitions/#animtype-font-weight
 impl Interpolate for FontWeight {
     #[inline]
     fn interpolate(&self, other: &FontWeight, time: f64)
@@ -690,6 +710,7 @@ impl Interpolate for FontWeight {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-rect
 impl Interpolate for ClipRect {
     #[inline]
     fn interpolate(&self, other: &ClipRect, time: f64)
@@ -706,6 +727,7 @@ impl Interpolate for ClipRect {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-simple-list
 impl Interpolate for BackgroundPosition {
     #[inline]
     fn interpolate(&self, other: &BackgroundPosition, time: f64)
@@ -720,6 +742,7 @@ impl Interpolate for BackgroundPosition {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-shadow-list
 impl Interpolate for TextShadow {
     #[inline]
     fn interpolate(&self, other: &TextShadow, time: f64)
@@ -736,6 +759,7 @@ impl Interpolate for TextShadow {
     }
 }
 
+/// https://drafts.csswg.org/css-transitions/#animtype-shadow-list
 impl Interpolate for TextShadowList {
     #[inline]
     fn interpolate(&self, other: &TextShadowList, time: f64)
@@ -789,7 +813,7 @@ fn can_interpolate_list(from_list: &[TransformOperation],
 }
 
 /// Interpolate two transform lists.
-/// http://dev.w3.org/csswg/css-transforms/#interpolation-of-transforms
+/// https://drafts.csswg.org/css-transforms/#interpolation-of-transforms
 fn interpolate_transform_list(from_list: &[TransformOperation],
                               to_list: &[TransformOperation],
                               time: f64) -> TransformList {
@@ -849,7 +873,7 @@ fn interpolate_transform_list(from_list: &[TransformOperation],
 
 /// Build an equivalent 'identity transform function list' based
 /// on an existing transform list.
-/// http://dev.w3.org/csswg/css-transforms/#none-transform-animation
+/// https://drafts.csswg.org/css-transforms/#none-transform-animation
 fn build_identity_transform_list(list: &[TransformOperation]) -> Vec<TransformOperation> {
     let mut result = vec!();
 
@@ -884,27 +908,27 @@ fn build_identity_transform_list(list: &[TransformOperation]) -> Vec<TransformOp
     result
 }
 
+/// https://drafts.csswg.org/css-transforms/#interpolation-of-transforms
 impl Interpolate for TransformList {
     #[inline]
     fn interpolate(&self, other: &TransformList, time: f64) -> Option<TransformList> {
-        // http://dev.w3.org/csswg/css-transforms/#interpolation-of-transforms
         let result = match (&self.0, &other.0) {
             (&Some(ref from_list), &Some(ref to_list)) => {
-                // Two lists of transforms
+                // https://drafts.csswg.org/css-transforms/#transform-transform-animation
                 interpolate_transform_list(from_list, &to_list, time)
             }
             (&Some(ref from_list), &None) => {
-                // http://dev.w3.org/csswg/css-transforms/#none-transform-animation
+                // https://drafts.csswg.org/css-transforms/#none-transform-animation
                 let to_list = build_identity_transform_list(from_list);
                 interpolate_transform_list(from_list, &to_list, time)
             }
             (&None, &Some(ref to_list)) => {
-                // http://dev.w3.org/csswg/css-transforms/#none-transform-animation
+                // https://drafts.csswg.org/css-transforms/#none-transform-animation
                 let from_list = build_identity_transform_list(to_list);
                 interpolate_transform_list(&from_list, to_list, time)
             }
             _ => {
-                // http://dev.w3.org/csswg/css-transforms/#none-none-animation
+                // https://drafts.csswg.org/css-transforms/#none-none-animation
                 TransformList(None)
             }
         };
@@ -914,7 +938,9 @@ impl Interpolate for TransformList {
 }
 
 /// Accesses an element of an array, "wrapping around" using modular arithmetic. This is needed
-/// to handle values of differing lengths according to CSS-TRANSITIONS § 2.
+/// to handle [repeatable lists][lists] of differing lengths.
+///
+/// [lists]: https://drafts.csswg.org/css-transitions/#animtype-repeatable-list
 pub trait GetMod {
     type Item;
     fn get_mod(&self, i: usize) -> &Self::Item;

components/style/attr.rs

@@ -2,6 +2,10 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! Parsed representations of [DOM attributes][attr].
+//!
+//! [attr]: https://dom.spec.whatwg.org/#interface-attr
+
 use app_units::Au;
 use cssparser::{self, Color, RGBA};
 use euclid::num::Zero;
@@ -332,8 +336,6 @@ impl ::std::ops::Deref for AttrValue {
     }
 }
 
-/// HTML5 § 2.4.4.5.
-///
 /// https://html.spec.whatwg.org/multipage/#rules-for-parsing-non-zero-dimension-values
 pub fn parse_nonzero_length(value: &str) -> LengthOrPercentageOrAuto {
     match parse_length(value) {
@@ -343,7 +345,9 @@ pub fn parse_nonzero_length(value: &str) -> LengthOrPercentageOrAuto {
     }
 }
 
-/// Parses a legacy color per HTML5 § 2.4.6. If unparseable, `Err` is returned.
+/// Parses a [legacy color][color]. If unparseable, `Err` is returned.
+///
+/// [color]: https://html.spec.whatwg.org/multipage/#rules-for-parsing-a-legacy-colour-value
 pub fn parse_legacy_color(mut input: &str) -> Result<RGBA, ()> {
     // Steps 1 and 2.
     if input.is_empty() {
@@ -471,10 +475,10 @@ pub fn parse_legacy_color(mut input: &str) -> Result<RGBA, ()> {
     }
 }
 
-/// TODO: this function can be rewritten to return Result<LengthOrPercentage, _>
+/// Parses a [dimension value][dim]. If unparseable, `Auto` is returned.
-/// Parses a dimension value per HTML5 § 2.4.4.4. If unparseable, `Auto` is
+///
-/// returned.
+/// [dim]: https://html.spec.whatwg.org/multipage/#rules-for-parsing-dimension-values
-/// https://html.spec.whatwg.org/multipage/#rules-for-parsing-dimension-values
+// TODO: this function can be rewritten to return Result<LengthOrPercentage, _>
 pub fn parse_length(mut value: &str) -> LengthOrPercentageOrAuto {
     // Steps 1 & 2 are not relevant
 
@@ -540,6 +544,7 @@ pub fn parse_length(mut value: &str) -> LengthOrPercentageOrAuto {
     }
 }
 
+/// A struct that uniquely identifies an element's attribute.
 #[derive(Clone, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
 pub struct AttrIdentifier {

components/style/context.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! The context within which style is calculated.
+
 use animation::Animation;
 use app_units::Au;
 use dom::OpaqueNode;

components/style/custom_properties.rs

@@ -2,6 +2,10 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! Support for [custom properties for cascading variables][custom].
+//!
+//! [custom]: https://drafts.csswg.org/css-variables/
+
 use cssparser::{Delimiter, Parser, SourcePosition, ToCss, Token, TokenSerializationType};
 use properties::DeclaredValue;
 use std::ascii::AsciiExt;

components/style/data.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! Per-node data used in style calculation.
+
 use properties::ComputedValues;
 use selectors::parser::SelectorImpl;
 use std::collections::HashMap;

components/style/dom.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! Types and traits used to access the DOM from style calculation.
+
 #![allow(unsafe_code)]
 
 use context::SharedStyleContext;

components/style/element_state.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! States elements can be in.
+
 bitflags! {
     #[doc = "Event-based element states."]
     #[cfg_attr(feature = "servo", derive(HeapSizeOf))]

components/style/error_reporting.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! Types used to report parsing errors.
+
 use cssparser::{Parser, SourcePosition};
 use log;
 

components/style/font_face.rs

@@ -2,6 +2,10 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! The [`@font-face`][ff] at-rule.
+//!
+//! [ff]: https://drafts.csswg.org/css-fonts/#at-font-face-rule
+
 use computed_values::font_family::FontFamily;
 use cssparser::{AtRuleParser, DeclarationListParser, DeclarationParser, Parser};
 use parser::{ParserContext, log_css_error};

components/style/lib.rs

@@ -2,6 +2,27 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! Calculate [specified][specified] and [computed values][computed] from a
+//! tree of DOM nodes and a set of stylesheets.
+//!
+//! [computed]: https://drafts.csswg.org/css-cascade/#computed
+//! [specified]: https://drafts.csswg.org/css-cascade/#specified
+//!
+//! In particular, this crate contains the definitions of supported properties,
+//! the code to parse them into specified values and calculate the computed
+//! values based on the specified values, as well as the code to serialize both
+//! specified and computed values.
+//!
+//! The main entry point is [`recalc_style_at`][recalc_style_at].
+//!
+//! [recalc_style_at]: traversal/fn.recalc_style_at.html
+//!
+//! Major dependencies are the [cssparser][cssparser] and [selectors][selectors]
+//! crates.
+//!
+//! [cssparser]: ../cssparser/index.html
+//! [selectors]: ../selectors/index.html
+
 // FIXME: replace discriminant_value with per-enum methods that use `match`?
 #![feature(core_intrinsics)]
 
@@ -75,6 +96,7 @@ pub mod traversal;
 pub mod values;
 pub mod viewport;
 
+/// The CSS properties supported by the style system.
 // Generated from the properties.mako.rs template by build.rs
 #[macro_use]
 #[allow(unsafe_code)]
@@ -84,6 +106,9 @@ pub mod properties {
 
 macro_rules! reexport_computed_values {
     ( $( $name: ident )+ ) => {
+        /// Types for [computed values][computed].
+        ///
+        /// [computed]: https://drafts.csswg.org/css-cascade/#computed
         pub mod computed_values {
             $(
                 pub use properties::longhands::$name::computed_value as $name;

components/style/matching.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! High-level interface to CSS selector matching.
+
 #![allow(unsafe_code)]
 
 use animation::{self, Animation};
@@ -27,8 +29,6 @@ use util::cache::{LRUCache, SimpleHashCache};
 use util::opts;
 use util::vec::ForgetfulSink;
 
-/// High-level interface to CSS selector matching.
-
 fn create_common_style_affecting_attributes_from_element<E: TElement>(element: &E)
                                                          -> CommonStyleAffectingAttributes {
     let mut flags = CommonStyleAffectingAttributes::empty();

components/style/media_queries.rs

@@ -2,6 +2,10 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! [Media queries][mq].
+//!
+//! [mq]: https://drafts.csswg.org/mediaqueries/
+
 use app_units::Au;
 use cssparser::{Delimiter, Parser, Token};
 use euclid::size::{Size2D, TypedSize2D};

components/style/parser.rs

@@ -2,6 +2,7 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! The context within which CSS code is parsed.
 
 use cssparser::{Parser, SourcePosition};
 use error_reporting::ParseErrorReporter;

components/style/restyle_hints.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! Restyle hints: an optimization to avoid unnecessarily matching selectors.
+
 use attr::{AttrIdentifier, AttrValue};
 use element_state::*;
 use selector_impl::SelectorImplExt;

components/style/selector_impl.rs

@@ -1,6 +1,9 @@
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+//! The pseudo-classes and pseudo-elements supported by the style system.
+
 use element_state::ElementState;
 use properties::{self, ServoComputedValues};
 use selector_matching::{USER_OR_USER_AGENT_STYLESHEETS, QUIRKS_MODE_STYLESHEET};

components/style/selector_matching.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! Selector matching.
+
 use dom::PresentationalHintsSynthetizer;
 use element_state::*;
 use error_reporting::StdoutErrorReporter;

components/style/servo.rs

@@ -1,6 +1,9 @@
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+//! Concrete types for servo Style implementation
+
 use context;
 use data;
 use properties::ServoComputedValues;
@@ -8,7 +11,6 @@ use selector_impl::ServoSelectorImpl;
 use selector_matching;
 use stylesheets;
 
-/// Concrete types for servo Style implementation
 pub type Stylesheet = stylesheets::Stylesheet<ServoSelectorImpl>;
 pub type PrivateStyleData = data::PrivateStyleData<ServoSelectorImpl, ServoComputedValues>;
 pub type Stylist = selector_matching::Stylist<ServoSelectorImpl>;

components/style/stylesheets.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! Style sheets and their CSS rules.
+
 use cssparser::{AtRuleParser, Parser, QualifiedRuleParser, decode_stylesheet_bytes};
 use cssparser::{AtRuleType, RuleListParser};
 use encoding::EncodingRef;

components/style/traversal.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! Traversing the DOM tree; the bloom filter.
+
 use context::{SharedStyleContext, StyleContext};
 use dom::{OpaqueNode, TNode, TRestyleDamage, UnsafeNode};
 use matching::{ApplicableDeclarations, ElementMatchMethods, MatchMethods, StyleSharingResult};
@@ -142,12 +144,13 @@ pub fn remove_from_bloom_filter<'a, N, C, Impl>(context: &C, root: OpaqueNode, n
 pub trait DomTraversalContext<N: TNode>  {
     type SharedContext: Sync + 'static;
     fn new<'a>(&'a Self::SharedContext, OpaqueNode) -> Self;
+    /// Process `node` on the way down, before its children have been processed.
     fn process_preorder(&self, node: N);
+    /// Process `node` on the way up, after its children have been processed.
     fn process_postorder(&self, node: N);
 }
 
-/// The recalc-style-for-node traversal, which styles each node and must run before
+/// Calculates the style for a single node.
-/// layout computation. This computes the styles applied to each node.
 #[inline]
 #[allow(unsafe_code)]
 pub fn recalc_style_at<'a, N, C>(context: &'a C,

components/style/values.rs

@@ -2,6 +2,10 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! Common [values][values] used in CSS.
+//!
+//! [values]: https://drafts.csswg.org/css-values/
+
 pub use cssparser::RGBA;
 
 use app_units::Au;

components/style/viewport.rs

@@ -2,6 +2,11 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+//! The [`@viewport`][at] at-rule and [`meta`][meta] element.
+//!
+//! [at]: https://drafts.csswg.org/css-device-adapt/#atviewport-rule
+//! [meta]: https://drafts.csswg.org/css-device-adapt/#viewport-meta
+
 use app_units::Au;
 use cssparser::ToCss;
 use cssparser::{AtRuleParser, DeclarationListParser, DeclarationParser, Parser, parse_important};