style: Prevent more missing docs in the values module.

components/style/values/computed/basic_shape.rs

@@ -18,6 +18,7 @@ pub use values::specified::basic_shape::{FillRule, GeometryBox, ShapeBox};
 
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum ShapeSource<T> {
     Url(SpecifiedUrl),
     Shape(BasicShape, Option<T>),
@@ -51,6 +52,7 @@ impl<T: ToCss> ToCss for ShapeSource<T> {
 
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum BasicShape {
     Inset(InsetRect),
     Circle(Circle),
@@ -71,6 +73,7 @@ impl ToCss for BasicShape {
 
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct InsetRect {
     pub top: LengthOrPercentage,
     pub right: LengthOrPercentage,
@@ -100,6 +103,7 @@ impl ToCss for InsetRect {
 
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct Circle {
     pub radius: ShapeRadius,
     pub position: Position,
@@ -115,6 +119,7 @@ impl ToCss for Circle {
 
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct Ellipse {
     pub semiaxis_x: ShapeRadius,
     pub semiaxis_y: ShapeRadius,
@@ -138,6 +143,7 @@ impl ToCss for Ellipse {
 
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 /// https://drafts.csswg.org/css-shapes/#funcdef-polygon
 pub struct Polygon {
     pub fill: FillRule,
@@ -168,6 +174,7 @@ impl ToCss for Polygon {
 /// https://drafts.csswg.org/css-shapes/#typedef-shape-radius
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum ShapeRadius {
     Length(LengthOrPercentage),
     ClosestSide,
@@ -193,6 +200,7 @@ impl ToCss for ShapeRadius {
 /// https://drafts.csswg.org/css-backgrounds-3/#border-radius
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct BorderRadius {
     pub top_left: BorderRadiusSize,
     pub top_right: BorderRadiusSize,

components/style/values/computed/image.rs

@@ -51,6 +51,7 @@ impl ToComputedValue for specified::Image {
 /// https://drafts.csswg.org/css-images/#image-values
 #[derive(Clone, PartialEq)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum Image {
     Url(SpecifiedUrl),
     Gradient(Gradient),
@@ -174,6 +175,7 @@ impl ToComputedValue for specified::Gradient {
 /// https://drafts.csswg.org/css-images/#gradients
 #[derive(Clone, PartialEq)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum GradientKind {
     Linear(AngleOrCorner),
     Radial(EndingShape, Position),
@@ -271,6 +273,7 @@ impl ToComputedValue for specified::ColorStop {
 /// https://drafts.csswg.org/css-images/#valdef-radial-gradient-ending-shape
 #[derive(Clone, PartialEq)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum EndingShape {
     Circle(LengthOrKeyword),
     Ellipse(LengthOrPercentageOrKeyword),
@@ -336,6 +339,7 @@ impl ToComputedValue for specified::GradientEndingShape {
 /// https://drafts.csswg.org/css-images/#valdef-radial-gradient-size
 #[derive(Clone, PartialEq)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum LengthOrKeyword {
     Length(Length),
     Keyword(SizeKeyword),
@@ -394,6 +398,7 @@ impl ToComputedValue for specified::LengthOrKeyword {
 /// https://drafts.csswg.org/css-images/#valdef-radial-gradient-size
 #[derive(Clone, PartialEq)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum LengthOrPercentageOrKeyword {
     LengthOrPercentage(LengthOrPercentage, LengthOrPercentage),
     Keyword(SizeKeyword),
@@ -458,6 +463,7 @@ impl ToComputedValue for specified::LengthOrPercentageOrKeyword {
 
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum AngleOrCorner {
     Angle(Angle),
     Corner(HorizontalDirection, VerticalDirection)

components/style/values/computed/length.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/. */
 
+//! `<length>` computed values, and related ones.
+
 use app_units::Au;
 use ordered_float::NotNaN;
 use std::fmt;
@@ -16,6 +18,7 @@ pub use values::specified::{Angle, BorderStyle, Time, UrlOrNone};
 
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct CalcLengthOrPercentage {
     pub length: Au,
     pub percentage: Option<CSSFloat>,
@@ -23,11 +26,13 @@ pub struct CalcLengthOrPercentage {
 
 impl CalcLengthOrPercentage {
     #[inline]
+    #[allow(missing_docs)]
     pub fn length(&self) -> Au {
         self.length
     }
 
     #[inline]
+    #[allow(missing_docs)]
     pub fn percentage(&self) -> CSSFloat {
         self.percentage.unwrap_or(0.)
     }
@@ -130,6 +135,7 @@ impl ToComputedValue for specified::CalcLengthOrPercentage {
 
 #[derive(PartialEq, Clone, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum LengthOrPercentage {
     Length(Au),
     Percentage(CSSFloat),
@@ -138,6 +144,7 @@ pub enum LengthOrPercentage {
 
 impl LengthOrPercentage {
     #[inline]
+    #[allow(missing_docs)]
     pub fn zero() -> LengthOrPercentage {
         LengthOrPercentage::Length(Au(0))
     }
@@ -154,6 +161,7 @@ impl LengthOrPercentage {
         }
     }
 
+    #[allow(missing_docs)]
     pub fn to_hash_key(&self) -> (Au, NotNaN<f32>) {
         use self::LengthOrPercentage::*;
         match *self {
@@ -223,6 +231,7 @@ impl ToCss for LengthOrPercentage {
 
 #[derive(PartialEq, Clone, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum LengthOrPercentageOrAuto {
     Length(Au),
     Percentage(CSSFloat),
@@ -311,6 +320,7 @@ impl ToCss for LengthOrPercentageOrAuto {
 
 #[derive(PartialEq, Clone, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum LengthOrPercentageOrAutoOrContent {
     Length(Au),
     Percentage(CSSFloat),
@@ -397,6 +407,7 @@ impl ToCss for LengthOrPercentageOrAutoOrContent {
 
 #[derive(PartialEq, Clone, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum LengthOrPercentageOrNone {
     Length(Au),
     Percentage(CSSFloat),
@@ -469,12 +480,17 @@ impl ToCss for LengthOrPercentageOrNone {
     }
 }
 
+/// A computed `<length>` value.
+pub type Length = Au;
+
+/// Either a computed `<length>` or the `none` keyword.
 pub type LengthOrNone = Either<Length, None_>;
 
+/// Either a computed `<length>` or the `auto` keyword.
 pub type LengthOrAuto = Either<Length, Auto>;
 
+/// Either a computed `<length>` or a `<number>` value.
 pub type LengthOrNumber = Either<Length, Number>;
 
+/// Either a computed `<length>` or the `normal` keyword.
 pub type LengthOrNormal = Either<Length, Normal>;
-
-pub type Length = Au;

components/style/values/computed/mod.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/. */
 
+//! Computed values.
+
 use app_units::Au;
 use euclid::size::Size2D;
 use font_metrics::FontMetricsProvider;
@@ -24,23 +26,41 @@ pub mod image;
 pub mod length;
 pub mod position;
 
+/// A `Context` is all the data a specified value could ever need to compute
+/// itself and be transformed to a computed value.
 pub struct Context<'a> {
+    /// Whether the current element is the root element.
     pub is_root_element: bool,
+
+    /// The current viewport size.
     pub viewport_size: Size2D<Au>,
+
+    /// The style we're inheriting from.
     pub inherited_style: &'a ComputedValues,
 
     /// Values access through this need to be in the properties "computed
     /// early": color, text-decoration, font-size, display, position, float,
     /// border-*-style, outline-style, font-family, writing-mode...
     pub style: ComputedValues,
+
+    /// A font metrics provider, used to access font metrics to implement
+    /// font-relative units.
+    ///
+    /// TODO(emilio): This should be required, see #14079.
     pub font_metrics_provider: Option<&'a FontMetricsProvider>,
 }
 
 impl<'a> Context<'a> {
+    /// Whether the current element is the root element.
     pub fn is_root_element(&self) -> bool { self.is_root_element }
+    /// The current viewport size.
     pub fn viewport_size(&self) -> Size2D<Au> { self.viewport_size }
+    /// The style we're inheriting from.
     pub fn inherited_style(&self) -> &ComputedValues { &self.inherited_style }
+    /// The current style. Note that only "eager" properties should be accessed
+    /// from here, see the comment in the member.
     pub fn style(&self) -> &ComputedValues { &self.style }
+    /// A mutable reference to the current style.
     pub fn mutate_style(&mut self) -> &mut ComputedValues { &mut self.style }
 
     /// Creates a dummy computed context for use in multiple places, like
@@ -58,11 +78,15 @@ impl<'a> Context<'a> {
     }
 }
 
+/// A trait to represent the conversion between computed and specified values.
 pub trait ToComputedValue {
+    /// The computed value type we're going to be converted to.
     type ComputedValue;
 
+    /// Convert a specified value to a computed value, using itself and the data
+    /// inside the `Context`.
     #[inline]
-    fn to_computed_value(&self, _context: &Context) -> Self::ComputedValue;
+    fn to_computed_value(&self, context: &Context) -> Self::ComputedValue;
 
     #[inline]
     /// Convert a computed value to specified value form.
@@ -137,9 +161,11 @@ impl ToComputedValue for specified::Length {
 
 #[derive(Debug, PartialEq, Clone, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct BorderRadiusSize(pub Size2D<LengthOrPercentage>);
 
 impl BorderRadiusSize {
+    #[allow(missing_docs)]
     pub fn zero() -> BorderRadiusSize {
         BorderRadiusSize(Size2D::new(LengthOrPercentage::Length(Au(0)), LengthOrPercentage::Length(Au(0))))
     }
@@ -173,6 +199,7 @@ impl ToCss for BorderRadiusSize {
 
 #[derive(Debug, PartialEq, Clone, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct Shadow {
     pub offset_x: Au,
     pub offset_y: Au,
@@ -182,5 +209,8 @@ pub struct Shadow {
     pub inset: bool,
 }
 
+/// A `<number>` value.
 pub type Number = CSSFloat;
+
+/// A type used for opacity.
 pub type Opacity = CSSFloat;

components/style/values/computed/position.rs

@@ -13,6 +13,7 @@ use values::computed::LengthOrPercentage;
 
 #[derive(Debug, Clone, PartialEq, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct Position {
     pub horizontal: LengthOrPercentage,
     pub vertical: LengthOrPercentage,
@@ -29,6 +30,7 @@ impl ToCss for Position {
 
 #[derive(Debug, Clone, PartialEq, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct HorizontalPosition(pub LengthOrPercentage);
 
 impl ToCss for HorizontalPosition {
@@ -39,6 +41,7 @@ impl ToCss for HorizontalPosition {
 
 #[derive(Debug, Clone, PartialEq, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct VerticalPosition(pub LengthOrPercentage);
 
 impl ToCss for VerticalPosition {

components/style/values/mod.rs

@@ -6,6 +6,8 @@
 //!
 //! [values]: https://drafts.csswg.org/css-values/
 
+#![deny(missing_docs)]
+
 pub use cssparser::{RGBA, Parser};
 use parser::{Parse, ParserContext};
 use std::fmt::{self, Debug};
@@ -16,7 +18,7 @@ macro_rules! define_numbered_css_keyword_enum {
         define_numbered_css_keyword_enum!($name: $( $css => $variant = $value ),+);
     };
     ($name: ident: $( $css: expr => $variant: ident = $value: expr ),+) => {
-        #[allow(non_camel_case_types)]
+        #[allow(non_camel_case_types, missing_docs)]
         #[derive(Clone, Eq, PartialEq, PartialOrd, Ord, Copy, RustcEncodable, Debug)]
         #[cfg_attr(feature = "servo", derive(HeapSizeOf, Deserialize, Serialize))]
         pub enum $name {
@@ -24,6 +26,7 @@ macro_rules! define_numbered_css_keyword_enum {
         }
 
         impl $name {
+            #[allow(missing_docs)]
             pub fn parse(input: &mut ::cssparser::Parser) -> Result<$name, ()> {
                 match_ignore_ascii_case! { try!(input.expect_ident()),
                     $( $css => Ok($name::$variant), )+
@@ -53,14 +56,14 @@ pub type CSSFloat = f32;
 /// The default font size.
 pub const FONT_MEDIUM_PX: i32 = 16;
 
-/// A trait used to represent whether this value has viewport units.
+/// A trait used to query whether this value has viewport units.
 pub trait HasViewportPercentage {
     /// Returns true if this value has viewport units.
     fn has_viewport_percentage(&self) -> bool;
 }
 
-/// A trait used as a marker to represent that a given value has no viewport
+/// A trait used as a marker to represent that a given type may never contain
-/// units.
+/// viewport units.
 pub trait NoViewportPercentage {}
 
 impl<T> HasViewportPercentage for T
@@ -78,6 +81,7 @@ macro_rules! define_keyword_type {
     ($name: ident, $css: expr) => {
         #[derive(Clone, PartialEq, Copy)]
         #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+        #[allow(missing_docs)]
         pub struct $name;
 
         impl ::style_traits::ToCss for $name {
@@ -109,8 +113,11 @@ define_keyword_type!(Normal, "normal");
 
 #[derive(Clone, PartialEq, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+/// A struct representing one of two kinds of values.
 pub enum Either<A, B> {
+    /// The first value.
     First(A),
+    /// The second kind of value.
     Second(B),
 }
 

components/style/values/specified/basic_shape.rs

@@ -24,6 +24,7 @@ use values::specified::url::SpecifiedUrl;
 /// shape-outside uses ShapeSource<ShapeBox>
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum ShapeSource<T> {
     Url(SpecifiedUrl),
     Shape(BasicShape, Option<T>),
@@ -55,6 +56,7 @@ impl<T: ToCss> ToCss for ShapeSource<T> {
 }
 
 impl<T: Parse + PartialEq + Copy> ShapeSource<T> {
+    #[allow(missing_docs)]
     pub fn parse(context: &ParserContext, input: &mut Parser) -> Result<Self, ()> {
         if let Ok(_) = input.try(|input| input.expect_ident_matching("none")) {
             Ok(ShapeSource::None)
@@ -129,6 +131,7 @@ impl<T: ToComputedValue> ToComputedValue for ShapeSource<T> {
 
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum BasicShape {
     Inset(InsetRect),
     Circle(Circle),
@@ -205,6 +208,7 @@ impl ToComputedValue for BasicShape {
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
 /// https://drafts.csswg.org/css-shapes/#funcdef-inset
+#[allow(missing_docs)]
 pub struct InsetRect {
     pub top: LengthOrPercentage,
     pub right: LengthOrPercentage,
@@ -214,6 +218,7 @@ pub struct InsetRect {
 }
 
 impl InsetRect {
+    #[allow(missing_docs)]
     pub fn parse_function_arguments(context: &ParserContext, input: &mut Parser) -> Result<InsetRect, ()> {
         let (t, r, b, l) = try!(parse_four_sides(input, |i| LengthOrPercentage::parse(context, i)));
         let mut rect = InsetRect {
@@ -373,12 +378,14 @@ fn serialize_basicshape_position<W>(position: &Position, dest: &mut W)
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
 /// https://drafts.csswg.org/css-shapes/#funcdef-circle
+#[allow(missing_docs)]
 pub struct Circle {
     pub radius: ShapeRadius,
     pub position: Position,
 }
 
 impl Circle {
+    #[allow(missing_docs)]
     pub fn parse_function_arguments(context: &ParserContext, input: &mut Parser) -> Result<Circle, ()> {
         let radius = input.try(|i| ShapeRadius::parse(context, i)).ok().unwrap_or_else(Default::default);
         let position = if let Ok(_) = input.try(|input| input.expect_ident_matching("at")) {
@@ -450,6 +457,7 @@ impl ToComputedValue for Circle {
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
 /// https://drafts.csswg.org/css-shapes/#funcdef-ellipse
+#[allow(missing_docs)]
 pub struct Ellipse {
     pub semiaxis_x: ShapeRadius,
     pub semiaxis_y: ShapeRadius,
@@ -458,6 +466,7 @@ pub struct Ellipse {
 
 
 impl Ellipse {
+    #[allow(missing_docs)]
     pub fn parse_function_arguments(context: &ParserContext, input: &mut Parser) -> Result<Ellipse, ()> {
         let (a, b) = input.try(|input| -> Result<_, ()> {
             Ok((try!(ShapeRadius::parse(context, input)), try!(ShapeRadius::parse(context, input))))
@@ -537,12 +546,14 @@ impl ToComputedValue for Ellipse {
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
 /// https://drafts.csswg.org/css-shapes/#funcdef-polygon
+#[allow(missing_docs)]
 pub struct Polygon {
     pub fill: FillRule,
     pub coordinates: Vec<(LengthOrPercentage, LengthOrPercentage)>,
 }
 
 impl Polygon {
+    #[allow(missing_docs)]
     pub fn parse_function_arguments(context: &ParserContext, input: &mut Parser) -> Result<Polygon, ()> {
         let fill = input.try(|input| {
             let fill = FillRule::parse(context, input);
@@ -626,6 +637,7 @@ impl ToComputedValue for Polygon {
 /// https://drafts.csswg.org/css-shapes/#typedef-shape-radius
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum ShapeRadius {
     Length(LengthOrPercentage),
     ClosestSide,
@@ -690,6 +702,7 @@ impl ToComputedValue for ShapeRadius {
 /// https://drafts.csswg.org/css-backgrounds-3/#border-radius
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct BorderRadius {
     pub top_left: BorderRadiusSize,
     pub top_right: BorderRadiusSize,
@@ -792,6 +805,7 @@ impl ToComputedValue for BorderRadius {
 /// https://drafts.csswg.org/css-shapes/#typedef-fill-rule
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum FillRule {
     NonZero,
     EvenOdd,
@@ -830,6 +844,7 @@ impl ToCss for FillRule {
 /// https://drafts.fxtf.org/css-masking-1/#typedef-geometry-box
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum GeometryBox {
     Fill,
     Stroke,
@@ -868,6 +883,7 @@ impl ComputedValueAsSpecified for GeometryBox {}
 // https://drafts.csswg.org/css-shapes-1/#typedef-shape-box
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum ShapeBox {
     Margin,
     // https://drafts.csswg.org/css-backgrounds-3/#box

components/style/values/specified/grid.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/. */
 
+//! A grid line type.
+
 use cssparser::Parser;
 use parser::{Parse, ParserContext};
 use std::fmt;
@@ -9,9 +11,10 @@ use style_traits::ToCss;
 use values::NoViewportPercentage;
 use values::computed::ComputedValueAsSpecified;
 
-// https://drafts.csswg.org/css-grid/#typedef-grid-row-start-grid-line
 #[derive(PartialEq, Clone, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+/// https://drafts.csswg.org/css-grid/#typedef-grid-row-start-grid-line
+#[allow(missing_docs)]
 pub struct GridLine {
     pub is_span: bool,
     pub ident: Option<String>,

components/style/values/specified/image.rs

@@ -21,7 +21,9 @@ use values::specified::url::{SpecifiedUrl, UrlExtraData};
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
 pub enum Image {
+    /// A `<url()>` image.
     Url(SpecifiedUrl),
+    /// A `<gradient>` image.
     Gradient(Gradient),
 }
 
@@ -35,6 +37,7 @@ impl ToCss for Image {
 }
 
 impl Image {
+    #[allow(missing_docs)]
     pub fn parse(context: &ParserContext, input: &mut Parser) -> Result<Image, ()> {
         if let Ok(url) = input.try(|input| SpecifiedUrl::parse(context, input)) {
             return Ok(Image::Url(url));
@@ -151,7 +154,14 @@ impl Gradient {
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
 pub enum GradientKind {
+    /// A `<linear-gradient()>`:
+    ///
+    /// https://drafts.csswg.org/css-images/#funcdef-linear-gradient
     Linear(AngleOrCorner),
+
+    /// A `<radial-gradient()>`:
+    ///
+    /// https://drafts.csswg.org/css-images/#radial-gradients
     Radial(EndingShape, Position),
 }
 
@@ -234,6 +244,7 @@ fn parse_position(context: &ParserContext, input: &mut Parser) -> Result<Positio
 /// Specified values for an angle or a corner in a linear gradient.
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum AngleOrCorner {
     Angle(Angle),
     Corner(Option<HorizontalDirection>, Option<VerticalDirection>),
@@ -327,6 +338,7 @@ impl Parse for ColorStop {
 /// https://drafts.csswg.org/css-images/#valdef-radial-gradient-ending-shape
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum EndingShape {
     Circle(LengthOrKeyword),
     Ellipse(LengthOrPercentageOrKeyword),
@@ -351,6 +363,7 @@ impl ToCss for EndingShape {
 /// https://drafts.csswg.org/css-images/#valdef-radial-gradient-size
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum LengthOrKeyword {
     Length(Length),
     Keyword(SizeKeyword),
@@ -378,6 +391,7 @@ impl ToCss for LengthOrKeyword {
 /// https://drafts.csswg.org/css-images/#valdef-radial-gradient-size
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum LengthOrPercentageOrKeyword {
     LengthOrPercentage(LengthOrPercentage, LengthOrPercentage),
     Keyword(SizeKeyword),

components/style/values/specified/length.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/. */
 
+//! [Length values][length].
+//!
+//! [length]: https://drafts.csswg.org/css-values/#lengths
+
 use app_units::Au;
 use cssparser::{Parser, Token};
 use euclid::size::Size2D;
@@ -49,6 +53,8 @@ impl ToCss for FontRelativeLength {
 }
 
 impl FontRelativeLength {
+    /// Gets the first available font metrics from the current context's
+    /// font-family list.
     pub fn find_first_available_font_metrics(context: &Context) -> Option<FontMetrics> {
         use font_metrics::FontMetricsQueryResult::*;
         if let Some(ref metrics_provider) = context.font_metrics_provider {
@@ -62,8 +68,8 @@ impl FontRelativeLength {
         None
     }
 
-    // NB: The use_inherited flag is used to special-case the computation of
+    /// Computes the font-relative length. We use the use_inherited flag to
-    // font-family.
+    /// special-case the computation of font-size.
     pub fn to_computed_value(&self, context: &Context, use_inherited: bool) -> Au {
         let reference_font_size = if use_inherited {
             context.inherited_style().get_font().clone_font_size()
@@ -128,10 +134,17 @@ impl FontRelativeLength {
 
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+/// A viewport-relative length.
+///
+/// https://drafts.csswg.org/css-values/#viewport-relative-lengths
 pub enum ViewportPercentageLength {
+    /// A vw unit: https://drafts.csswg.org/css-values/#vw
     Vw(CSSFloat),
+    /// A vh unit: https://drafts.csswg.org/css-values/#vh
     Vh(CSSFloat),
+    /// https://drafts.csswg.org/css-values/#vmin
     Vmin(CSSFloat),
+    /// https://drafts.csswg.org/css-values/#vmax
     Vmax(CSSFloat)
 }
 
@@ -153,6 +166,7 @@ impl ToCss for ViewportPercentageLength {
 }
 
 impl ViewportPercentageLength {
+    /// Computes the given viewport-relative length for the given viewport size.
     pub fn to_computed_value(&self, viewport_size: Size2D<Au>) -> Au {
         macro_rules! to_unit {
             ($viewport_dimension:expr) => {
@@ -174,11 +188,13 @@ impl ViewportPercentageLength {
     }
 }
 
+/// HTML5 "character width", as defined in HTML5 § 14.5.4.
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
 pub struct CharacterWidth(pub i32);
 
 impl CharacterWidth {
+    /// Computes the given character width.
     pub fn to_computed_value(&self, reference_font_size: Au) -> Au {
         // This applies the *converting a character width to pixels* algorithm as specified
         // in HTML5 § 14.5.4.
@@ -190,11 +206,23 @@ impl CharacterWidth {
     }
 }
 
+/// A length.
+///
+/// https://drafts.csswg.org/css-values/#lengths
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
 pub enum Length {
+    /// An absolute length: https://drafts.csswg.org/css-values/#absolute-length
     Absolute(Au),  // application units
+
+    /// A font-relative length:
+    ///
+    /// https://drafts.csswg.org/css-values/#font-relative-lengths
     FontRelative(FontRelativeLength),
+
+    /// A viewport-relative length.
+    ///
+    /// https://drafts.csswg.org/css-values/#viewport-relative-lengths
     ViewportPercentage(ViewportPercentageLength),
 
     /// HTML5 "character width", as defined in HTML5 § 14.5.4.
@@ -203,6 +231,12 @@ pub enum Length {
     /// `Stylist::synthesize_rules_for_legacy_attributes()`.
     ServoCharacterWidth(CharacterWidth),
 
+    /// A calc expression.
+    ///
+    /// https://drafts.csswg.org/css-values/#calc-notation
+    ///
+    /// TODO(emilio): We have more `Calc` variants around, we should only use
+    /// one.
     Calc(CalcLengthOrPercentage, AllowedNumericType),
 }
 
@@ -281,7 +315,7 @@ const AU_PER_PT: CSSFloat = AU_PER_IN / 72.;
 const AU_PER_PC: CSSFloat = AU_PER_PT * 12.;
 
 impl Length {
-    // https://drafts.csswg.org/css-fonts-3/#font-size-prop
+    /// https://drafts.csswg.org/css-fonts-3/#font-size-prop
     pub fn from_str(s: &str) -> Option<Length> {
         Some(match_ignore_ascii_case! { s,
             "xx-small" => Length::Absolute(Au::from_px(FONT_MEDIUM_PX) * 3 / 5),
@@ -313,9 +347,13 @@ impl Length {
             _ => Err(())
         }
     }
+
+    /// Parse a non-negative length
     pub fn parse_non_negative(input: &mut Parser) -> Result<Length, ()> {
         Length::parse_internal(input, AllowedNumericType::NonNegative)
     }
+
+    /// Parse a given absolute or relative dimension.
     pub fn parse_dimension(value: CSSFloat, unit: &str) -> Result<Length, ()> {
         match_ignore_ascii_case! { unit,
             "px" => Ok(Length::from_px(value)),
@@ -338,6 +376,8 @@ impl Length {
             _ => Err(())
         }
     }
+
+    /// Get an absolute length from a px values.
     #[inline]
     pub fn from_px(px_value: CSSFloat) -> Length {
         Length::Absolute(Au((px_value * AU_PER_PX) as i32))
@@ -352,22 +392,29 @@ impl Parse for Length {
 
 impl<T> Either<Length, T> {
     #[inline]
+    #[allow(missing_docs)]
     pub fn parse_non_negative_length(_context: &ParserContext, input: &mut Parser) -> Result<Self, ()> {
         Length::parse_internal(input, AllowedNumericType::NonNegative).map(Either::First)
     }
 }
 
+/// A calc sum expression node.
 #[derive(Clone, Debug)]
 pub struct CalcSumNode {
+    /// The products of this node.
     pub products: Vec<CalcProductNode>,
 }
 
+/// A calc product expression node.
 #[derive(Clone, Debug)]
 pub struct CalcProductNode {
+    /// The values inside this product node.
     values: Vec<CalcValueNode>
 }
 
+/// A value inside a `Calc` expression.
 #[derive(Clone, Debug)]
+#[allow(missing_docs)]
 pub enum CalcValueNode {
     Length(Length),
     Angle(Angle),
@@ -378,6 +425,7 @@ pub enum CalcValueNode {
 }
 
 #[derive(Clone, Copy, PartialEq)]
+#[allow(missing_docs)]
 pub enum CalcUnit {
     Number,
     Integer,
@@ -389,6 +437,7 @@ pub enum CalcUnit {
 
 #[derive(Clone, PartialEq, Copy, Debug, Default)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct CalcLengthOrPercentage {
     pub absolute: Option<Au>,
     pub vw: Option<ViewportPercentageLength>,
@@ -403,6 +452,7 @@ pub struct CalcLengthOrPercentage {
 }
 
 impl CalcLengthOrPercentage {
+    /// Parse a calc sum node.
     pub fn parse_sum(input: &mut Parser, expected_unit: CalcUnit) -> Result<CalcSumNode, ()> {
         let mut products = Vec::new();
         products.push(try!(CalcLengthOrPercentage::parse_product(input, expected_unit)));
@@ -523,6 +573,7 @@ impl CalcLengthOrPercentage {
         }
     }
 
+    #[allow(missing_docs)]
     pub fn simplify_product(node: &CalcProductNode) -> Result<SimplifiedValueNode, ()> {
         let mut multiplier = 1.;
         let mut node_with_unit = None;
@@ -561,6 +612,7 @@ impl CalcLengthOrPercentage {
         CalcLengthOrPercentage::parse(input, CalcUnit::LengthOrPercentage)
     }
 
+    #[allow(missing_docs)]
     pub fn parse(input: &mut Parser,
                  expected_unit: CalcUnit) -> Result<CalcLengthOrPercentage, ()> {
         let ast = try!(CalcLengthOrPercentage::parse_sum(input, expected_unit));
@@ -631,6 +683,7 @@ impl CalcLengthOrPercentage {
         })
     }
 
+    #[allow(missing_docs)]
     pub fn parse_time(input: &mut Parser) -> Result<Time, ()> {
         let ast = try!(CalcLengthOrPercentage::parse_sum(input, CalcUnit::Time));
 
@@ -658,6 +711,7 @@ impl CalcLengthOrPercentage {
         }
     }
 
+    #[allow(missing_docs)]
     pub fn parse_angle(input: &mut Parser) -> Result<Angle, ()> {
         let ast = try!(CalcLengthOrPercentage::parse_sum(input, CalcUnit::Angle));
 
@@ -747,9 +801,12 @@ impl ToCss for CalcLengthOrPercentage {
      }
 }
 
+/// A percentage value.
+///
+/// [0 .. 100%] maps to [0.0 .. 1.0]
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
-pub struct Percentage(pub CSSFloat); // [0 .. 100%] maps to [0.0 .. 1.0]
+pub struct Percentage(pub CSSFloat);
 
 impl ToCss for Percentage {
     fn to_css<W>(&self, dest: &mut W) -> fmt::Result where W: fmt::Write {
@@ -769,8 +826,12 @@ impl Parse for Percentage {
     }
 }
 
+/// A length or a percentage value.
+///
+/// TODO(emilio): Does this make any sense vs. CalcLengthOrPercentage?
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum LengthOrPercentage {
     Length(Length),
     Percentage(Percentage),
@@ -797,6 +858,7 @@ impl ToCss for LengthOrPercentage {
     }
 }
 impl LengthOrPercentage {
+    /// Returns a `zero` length.
     pub fn zero() -> LengthOrPercentage {
         LengthOrPercentage::Length(Length::Absolute(Au(0)))
     }
@@ -819,6 +881,7 @@ impl LengthOrPercentage {
         }
     }
 
+    /// Parse a non-negative length.
     #[inline]
     pub fn parse_non_negative(input: &mut Parser) -> Result<LengthOrPercentage, ()> {
         LengthOrPercentage::parse_internal(input, AllowedNumericType::NonNegative)
@@ -832,8 +895,11 @@ impl Parse for LengthOrPercentage {
     }
 }
 
+/// TODO(emilio): Do the Length and Percentage variants make any sense with
+/// CalcLengthOrPercentage?
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum LengthOrPercentageOrAuto {
     Length(Length),
     Percentage(Percentage),
@@ -882,6 +948,8 @@ impl LengthOrPercentageOrAuto {
             _ => Err(())
         }
     }
+
+    /// Parse a non-negative length, percentage, or auto.
     #[inline]
     pub fn parse_non_negative(input: &mut Parser) -> Result<LengthOrPercentageOrAuto, ()> {
         LengthOrPercentageOrAuto::parse_internal(input, AllowedNumericType::NonNegative)
@@ -895,8 +963,11 @@ impl Parse for LengthOrPercentageOrAuto {
     }
 }
 
+/// TODO(emilio): Do the Length and Percentage variants make any sense with
+/// CalcLengthOrPercentage?
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum LengthOrPercentageOrNone {
     Length(Length),
     Percentage(Percentage),
@@ -944,6 +1015,7 @@ impl LengthOrPercentageOrNone {
             _ => Err(())
         }
     }
+    /// Parse a non-negative LengthOrPercentageOrNone.
     #[inline]
     pub fn parse_non_negative(input: &mut Parser) -> Result<LengthOrPercentageOrNone, ()> {
         LengthOrPercentageOrNone::parse_internal(input, AllowedNumericType::NonNegative)
@@ -957,19 +1029,31 @@ impl Parse for LengthOrPercentageOrNone {
     }
 }
 
+/// Either a `<length>` or the `none` keyword.
 pub type LengthOrNone = Either<Length, None_>;
 
+/// Either a `<length>` or the `normal` keyword.
 pub type LengthOrNormal = Either<Length, Normal>;
 
+/// Either a `<length>` or the `auto` keyword.
 pub type LengthOrAuto = Either<Length, Auto>;
 
+/// Either a `<length>` or a `<percentage>` or the `auto` keyword or the
+/// `content` keyword.
+///
+/// TODO(emilio): Do the Length and Percentage variants make any sense with
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
 pub enum LengthOrPercentageOrAutoOrContent {
+    /// A `<length>`.
     Length(Length),
+    /// A percentage.
     Percentage(Percentage),
+    /// A `calc` node.
     Calc(CalcLengthOrPercentage),
+    /// The `auto` keyword.
     Auto,
+    /// The `content` keyword.
     Content
 }
 
@@ -1018,9 +1102,11 @@ impl Parse for LengthOrPercentageOrAutoOrContent {
     }
 }
 
+/// Either a `<length>` or a `<number>`.
 pub type LengthOrNumber = Either<Length, Number>;
 
 impl LengthOrNumber {
+    /// Parse a non-negative LengthOrNumber.
     pub fn parse_non_negative(input: &mut Parser) -> Result<Self, ()> {
         if let Ok(v) = input.try(Length::parse_non_negative) {
             Ok(Either::First(v))

components/style/values/specified/mod.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/. */
 
+//! Specified values.
+//!
+//! TODO(emilio): Enhance docs.
+
 use app_units::Au;
 use cssparser::{self, Parser, Token};
 use euclid::size::Size2D;
@@ -35,6 +39,7 @@ impl NoViewportPercentage for i32 {}  // For PropertyDeclaration::Order
 
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct CSSColor {
     pub parsed: cssparser::Color,
     pub authored: Option<String>,
@@ -68,6 +73,7 @@ impl ToCss for CSSColor {
 
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct CSSRGBA {
     pub parsed: cssparser::RGBA,
     pub authored: Option<String>,
@@ -85,6 +91,7 @@ impl ToCss for CSSRGBA {
 }
 
 #[derive(Clone, Debug)]
+#[allow(missing_docs)]
 pub struct SimplifiedSumNode {
     values: Vec<SimplifiedValueNode>,
 }
@@ -100,6 +107,7 @@ impl<'a> Mul<CSSFloat> for &'a SimplifiedSumNode {
 }
 
 #[derive(Clone, Debug)]
+#[allow(missing_docs)]
 pub enum SimplifiedValueNode {
     Length(Length),
     Angle(Angle),
@@ -127,6 +135,7 @@ impl<'a> Mul<CSSFloat> for &'a SimplifiedValueNode {
     }
 }
 
+#[allow(missing_docs)]
 pub fn parse_integer(input: &mut Parser) -> Result<i32, ()> {
     match try!(input.next()) {
         Token::Number(ref value) => value.int_value.ok_or(()),
@@ -152,6 +161,7 @@ pub fn parse_integer(input: &mut Parser) -> Result<i32, ()> {
     }
 }
 
+#[allow(missing_docs)]
 pub fn parse_number(input: &mut Parser) -> Result<f32, ()> {
     match try!(input.next()) {
         Token::Number(ref value) => Ok(value.value),
@@ -179,20 +189,24 @@ pub fn parse_number(input: &mut Parser) -> Result<f32, ()> {
 
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct BorderRadiusSize(pub Size2D<LengthOrPercentage>);
 
 impl NoViewportPercentage for BorderRadiusSize {}
 
 impl BorderRadiusSize {
+    #[allow(missing_docs)]
     pub fn zero() -> BorderRadiusSize {
         let zero = LengthOrPercentage::Length(Length::Absolute(Au(0)));
             BorderRadiusSize(Size2D::new(zero, zero))
     }
 
+    #[allow(missing_docs)]
     pub fn new(width: LengthOrPercentage, height: LengthOrPercentage) -> BorderRadiusSize {
         BorderRadiusSize(Size2D::new(width, height))
     }
 
+    #[allow(missing_docs)]
     pub fn circle(radius: LengthOrPercentage) -> BorderRadiusSize {
         BorderRadiusSize(Size2D::new(radius, radius))
     }
@@ -228,11 +242,13 @@ impl ToCss for Angle {
 
 impl Angle {
     #[inline]
+    #[allow(missing_docs)]
     pub fn radians(self) -> f32 {
         self.0
     }
 
     #[inline]
+    #[allow(missing_docs)]
     pub fn from_radians(r: f32) -> Self {
         Angle(r)
     }
@@ -257,6 +273,7 @@ impl Parse for Angle {
 }
 
 impl Angle {
+    #[allow(missing_docs)]
     pub fn parse_dimension(value: CSSFloat, unit: &str) -> Result<Angle, ()> {
         match_ignore_ascii_case! { unit,
             "deg" => Ok(Angle(value * RAD_PER_DEG)),
@@ -268,8 +285,9 @@ impl Angle {
     }
 }
 
+#[allow(missing_docs)]
 pub fn parse_border_radius(context: &ParserContext, input: &mut Parser) -> Result<BorderRadiusSize, ()> {
-    input.try(|i| BorderRadiusSize::parse(context, i)).or_else(|()| {
+    input.try(|i| BorderRadiusSize::parse(context, i)).or_else(|_| {
         match_ignore_ascii_case! { try!(input.expect_ident()),
             "thin" => Ok(BorderRadiusSize::circle(
                              LengthOrPercentage::Length(Length::from_px(1.)))),
@@ -282,6 +300,7 @@ pub fn parse_border_radius(context: &ParserContext, input: &mut Parser) -> Resul
     })
 }
 
+#[allow(missing_docs)]
 pub fn parse_border_width(input: &mut Parser) -> Result<Length, ()> {
     input.try(Length::parse_non_negative).or_else(|()| {
         match_ignore_ascii_case! { try!(input.expect_ident()),
@@ -295,6 +314,7 @@ pub fn parse_border_width(input: &mut Parser) -> Result<Length, ()> {
 
 #[derive(Clone, PartialEq, Copy, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub enum BorderWidth {
     Thin,
     Medium,
@@ -317,6 +337,7 @@ impl Parse for BorderWidth {
 }
 
 impl BorderWidth {
+    #[allow(missing_docs)]
     pub fn from_length(length: Length) -> Self {
         BorderWidth::Width(length)
     }
@@ -382,6 +403,7 @@ define_numbered_css_keyword_enum! { BorderStyle:
 impl NoViewportPercentage for BorderStyle {}
 
 impl BorderStyle {
+    /// Whether this border style is either none or hidden.
     pub fn none_or_hidden(&self) -> bool {
         matches!(*self, BorderStyle::none | BorderStyle::hidden)
     }
@@ -435,6 +457,7 @@ impl ToCss for Time {
 
 #[derive(Clone, Copy, Debug, PartialEq, PartialOrd)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct Number(pub CSSFloat);
 
 impl NoViewportPercentage for Number {}
@@ -453,10 +476,12 @@ impl Number {
         }
     }
 
+    #[allow(missing_docs)]
     pub fn parse_non_negative(input: &mut Parser) -> Result<Number, ()> {
         Number::parse_with_minimum(input, 0.0)
     }
 
+    #[allow(missing_docs)]
     pub fn parse_at_least_one(input: &mut Parser) -> Result<Number, ()> {
         Number::parse_with_minimum(input, 1.0)
     }
@@ -482,6 +507,7 @@ impl ToCss for Number {
 
 #[derive(Clone, Copy, Debug, PartialEq, PartialOrd)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct Opacity(pub CSSFloat);
 
 impl NoViewportPercentage for Opacity {}
@@ -518,10 +544,12 @@ impl ToCss for Opacity {
     }
 }
 
+#[allow(missing_docs)]
 pub type UrlOrNone = Either<SpecifiedUrl, None_>;
 
 #[derive(Debug, Clone, PartialEq)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct Shadow {
     pub offset_x: Length,
     pub offset_y: Length,
@@ -573,6 +601,7 @@ impl ToComputedValue for Shadow {
 
 impl Shadow {
     // disable_spread_and_inset is for filter: drop-shadow(...)
+    #[allow(missing_docs)]
     pub fn parse(context:  &ParserContext, input: &mut Parser, disable_spread_and_inset: bool) -> Result<Shadow, ()> {
         use app_units::Au;
         let length_count = if disable_spread_and_inset { 3 } else { 4 };

components/style/values/specified/position.rs

@@ -20,8 +20,13 @@ use values::specified::{LengthOrPercentage, Percentage};
 
 #[derive(Debug, Clone, PartialEq, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+/// A [position][pos].
+///
+/// [pos]: https://drafts.csswg.org/css-values/#position
 pub struct Position {
+    /// The horizontal component.
     pub horizontal: HorizontalPosition,
+    /// The vertical component.
     pub vertical: VerticalPosition,
 }
 
@@ -59,8 +64,11 @@ impl HasViewportPercentage for Position {
 }
 
 impl Position {
-    pub fn new(mut first_position: Option<PositionComponent>, mut second_position: Option<PositionComponent>,
+    /// Create a new position value.
-               first_keyword: Option<PositionComponent>, second_keyword: Option<PositionComponent>)
+    pub fn new(mut first_position: Option<PositionComponent>,
+               mut second_position: Option<PositionComponent>,
+               first_keyword: Option<PositionComponent>,
+               second_keyword: Option<PositionComponent>)
                -> Result<Position, ()> {
         // Unwrap for checking if values are at right place.
         let first_key = first_keyword.unwrap_or(PositionComponent::Keyword(Keyword::Left));
@@ -150,6 +158,7 @@ impl Position {
         })
     }
 
+    /// Returns a "centered" position, as in "center center".
     pub fn center() -> Position {
         Position {
             horizontal: HorizontalPosition {
@@ -242,6 +251,7 @@ impl ToComputedValue for Position {
 
 #[derive(Debug, Clone, PartialEq, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct HorizontalPosition {
     pub keyword: Option<Keyword>,
     pub position: Option<LengthOrPercentage>,
@@ -249,11 +259,7 @@ pub struct HorizontalPosition {
 
 impl HasViewportPercentage for HorizontalPosition {
     fn has_viewport_percentage(&self) -> bool {
-        if let Some(pos) = self.position {
+        self.position.map_or(false, |pos| pos.has_viewport_percentage())
-            pos.has_viewport_percentage()
-        } else {
-            false
-        }
     }
 }
 
@@ -371,6 +377,7 @@ impl ToComputedValue for HorizontalPosition {
 
 #[derive(Debug, Clone, PartialEq, Copy)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
+#[allow(missing_docs)]
 pub struct VerticalPosition {
     pub keyword: Option<Keyword>,
     pub position: Option<LengthOrPercentage>,
@@ -378,11 +385,7 @@ pub struct VerticalPosition {
 
 impl HasViewportPercentage for VerticalPosition {
     fn has_viewport_percentage(&self) -> bool {
-        if let Some(pos) = self.position {
+        self.position.map_or(false, |pos| pos.has_viewport_percentage())
-            pos.has_viewport_percentage()
-        } else {
-            false
-        }
     }
 }
 
@@ -510,6 +513,7 @@ define_css_keyword_enum!(Keyword:
                          "y-end" => YEnd);
 
 impl Keyword {
+    /// Convert the given keyword to a length or a percentage.
     pub fn to_length_or_percentage(self) -> LengthOrPercentage {
         match self {
             Keyword::Center => LengthOrPercentage::Percentage(Percentage(0.5)),
@@ -532,10 +536,14 @@ enum PositionCategory {
     LengthOrPercentage,
 }
 
-// http://dev.w3.org/csswg/css2/colors.html#propdef-background-position
+/// A position component.
+///
+/// http://dev.w3.org/csswg/css2/colors.html#propdef-background-position
 #[derive(Clone, PartialEq, Copy)]
 pub enum PositionComponent {
+    /// A `<length>`
     Length(LengthOrPercentage),
+    /// A position keyword.
     Keyword(Keyword),
 }
 
@@ -568,6 +576,7 @@ impl HasViewportPercentage for PositionComponent {
 }
 
 impl PositionComponent {
+    /// Convert the given position component to a length or a percentage.
     #[inline]
     pub fn to_length_or_percentage(self) -> LengthOrPercentage {
         match self {

components/style/values/specified/url.rs

@@ -18,23 +18,29 @@ use style_traits::ToCss;
 use values::NoViewportPercentage;
 use values::computed::ComputedValueAsSpecified;
 
+/// A set of data needed in Gecko to represent a URL.
 #[derive(PartialEq, Clone, Debug)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf, Serialize, Deserialize, Eq))]
 pub struct UrlExtraData {
+    /// The base URI.
     #[cfg(feature = "gecko")]
     pub base: GeckoArcURI,
+    /// The referrer.
     #[cfg(feature = "gecko")]
     pub referrer: GeckoArcURI,
+    /// The principal that originated this URI.
     #[cfg(feature = "gecko")]
     pub principal: GeckoArcPrincipal,
 }
 
 impl UrlExtraData {
+    /// Constructs a `UrlExtraData`.
     #[cfg(feature = "servo")]
     pub fn make_from(_: &ParserContext) -> Option<UrlExtraData> {
         Some(UrlExtraData { })
     }
 
+    /// Constructs a `UrlExtraData`.
     #[cfg(feature = "gecko")]
     pub fn make_from(context: &ParserContext) -> Option<UrlExtraData> {
         match context.extra_data {
@@ -81,6 +87,11 @@ impl Parse for SpecifiedUrl {
 }
 
 impl SpecifiedUrl {
+    /// Try to parse a URL from a string value that is a valid CSS token for a
+    /// URL.
+    ///
+    /// Only returns `Err` for Gecko, in the case we can't construct a
+    /// `URLExtraData`.
     pub fn parse_from_string<'a>(url: Cow<'a, str>,
                                  context: &ParserContext)
                                  -> Result<Self, ()> {
@@ -104,14 +115,19 @@ impl SpecifiedUrl {
         })
     }
 
+    /// Get this URL's extra data.
     pub fn extra_data(&self) -> &UrlExtraData {
         &self.extra_data
     }
 
+    /// Returns the resolved url if it was valid.
     pub fn url(&self) -> Option<&ServoUrl> {
         self.resolved.as_ref()
     }
 
+    /// Return the resolved url as string, or the empty string if it's invalid.
+    ///
+    /// TODO(emilio): Should we return the original one if needed?
     pub fn as_str(&self) -> &str {
         match self.resolved {
             Some(ref url) => url.as_str(),
@@ -142,6 +158,7 @@ impl SpecifiedUrl {
         }
     }
 
+    /// Gets a new url from a string for unit tests.
     #[cfg(feature = "servo")]
     pub fn new_for_testing(url: &str) -> Self {
         SpecifiedUrl {