style: Document style_traits and deny missing docs on it.

components/style_traits/cursor.rs

@@ -8,14 +8,17 @@ use super::ToCss;
 
 macro_rules! define_cursor {
     ($( $css: expr => $variant: ident = $value: expr, )+) => {
+        /// https://drafts.csswg.org/css-ui/#cursor
         #[derive(Clone, Copy, Debug, Eq, PartialEq)]
         #[cfg_attr(feature = "servo", derive(Deserialize, Serialize, HeapSizeOf))]
         #[repr(u8)]
+        #[allow(missing_docs)]
         pub enum Cursor {
             $( $variant = $value ),+
         }
 
         impl Cursor {
+            /// Given a CSS keyword, get the corresponding cursor enum.
             pub fn from_css_keyword(keyword: &str) -> Result<Cursor, ()> {
                 match_ignore_ascii_case! { keyword,
                     $( concat!($css) => Ok(Cursor::$variant), )+

components/style_traits/lib.rs

@@ -9,7 +9,7 @@
 #![crate_name = "style_traits"]
 #![crate_type = "rlib"]
 
-#![deny(unsafe_code)]
+#![deny(unsafe_code, missing_docs)]
 
 #![cfg_attr(feature = "servo", feature(plugin))]
 #![cfg_attr(feature = "servo", feature(proc_macro))]

components/style_traits/values.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/. */
 
+//! Helper types and traits for the handling of CSS values.
+
 use app_units::Au;
 use std::fmt;
 
@@ -78,13 +80,14 @@ macro_rules! __define_css_keyword_enum__add_optional_traits {
 #[macro_export]
 macro_rules! __define_css_keyword_enum__actual {
     ($name: ident [ $( $derived_trait: ident),* ] [ $( $css: expr => $variant: ident ),+ ]) => {
-        #[allow(non_camel_case_types)]
+        #[allow(non_camel_case_types, missing_docs)]
         #[derive(Clone, Eq, PartialEq, Copy, Hash, RustcEncodable, Debug $(, $derived_trait )* )]
         pub enum $name {
             $( $variant ),+
         }
 
         impl $name {
+            /// Parse this property from a CSS input stream.
             pub fn parse(input: &mut ::cssparser::Parser) -> Result<$name, ()> {
                 match_ignore_ascii_case! { try!(input.expect_ident()),
                                            $( $css => Ok($name::$variant), )+
@@ -105,18 +108,23 @@ macro_rules! __define_css_keyword_enum__actual {
     }
 }
 
+/// Helper types for the handling of specified values.
 pub mod specified {
     use app_units::Au;
 
+    /// Whether to allow negative values or not.
     #[repr(u8)]
     #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
     #[derive(Clone, Copy, Debug, PartialEq, Eq)]
     pub enum AllowedNumericType {
+        /// Allow all kind of numeric values.
         All,
+        /// Allow only non-negative values.
         NonNegative
     }
 
     impl AllowedNumericType {
+        /// Whether value is valid for this allowed numeric type.
         #[inline]
         pub fn is_ok(&self, value: f32) -> bool {
             match *self {
@@ -125,6 +133,7 @@ pub mod specified {
             }
         }
 
+        /// Clamp the value following the rules of this numeric type.
         #[inline]
         pub fn clamp(&self, val: Au) -> Au {
             use std::cmp;

components/style_traits/viewport.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/. */
 
+//! Helper types for the `@viewport` rule.
+
 use {PagePx, ViewportPx};
 use cssparser::{Parser, ToCss};
 use euclid::scale_factor::ScaleFactor;
@@ -20,16 +22,25 @@ define_css_keyword_enum!(Orientation:
                          "landscape" => Landscape);
 
 
+/// A set of viewport descriptors:
+///
+/// https://drafts.csswg.org/css-device-adapt/#viewport-desc
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "servo", derive(Deserialize, Serialize, HeapSizeOf))]
 pub struct ViewportConstraints {
+    /// Width and height:
+    ///  * https://drafts.csswg.org/css-device-adapt/#width-desc
+    ///  * https://drafts.csswg.org/css-device-adapt/#height-desc
     pub size: TypedSize2D<f32, ViewportPx>,
-
+    /// https://drafts.csswg.org/css-device-adapt/#zoom-desc
     pub initial_zoom: ScaleFactor<f32, PagePx, ViewportPx>,
+    /// https://drafts.csswg.org/css-device-adapt/#min-max-width-desc
     pub min_zoom: Option<ScaleFactor<f32, PagePx, ViewportPx>>,
+    /// https://drafts.csswg.org/css-device-adapt/#min-max-width-desc
     pub max_zoom: Option<ScaleFactor<f32, PagePx, ViewportPx>>,
-
+    /// https://drafts.csswg.org/css-device-adapt/#user-zoom-desc
     pub user_zoom: UserZoom,
+    /// https://drafts.csswg.org/css-device-adapt/#orientation-desc
     pub orientation: Orientation
 }
 
@@ -53,19 +64,21 @@ impl ToCss for ViewportConstraints {
     }
 }
 
-/// Zoom is a number | percentage | auto
-/// See http://dev.w3.org/csswg/css-device-adapt/#descdef-viewport-zoom
+/// https://drafts.csswg.org/css-device-adapt/#descdef-viewport-zoom
 #[derive(Copy, Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "servo", derive(HeapSizeOf))]
 pub enum Zoom {
+    /// A number value.
     Number(f32),
+    /// A percentage value.
     Percentage(f32),
+    /// The `auto` keyword.
     Auto,
 }
 
 impl ToCss for Zoom {
     fn to_css<W>(&self, dest: &mut W) -> fmt::Result
-        where W: fmt::Write
+        where W: fmt::Write,
     {
         match *self {
             Zoom::Number(number) => write!(dest, "{}", number),
@@ -76,6 +89,9 @@ impl ToCss for Zoom {
 }
 
 impl Zoom {
+    /// Parse a zoom value per:
+    ///
+    /// https://drafts.csswg.org/css-device-adapt/#descdef-viewport-zoom
     pub fn parse(input: &mut Parser) -> Result<Zoom, ()> {
         use cssparser::Token;
 
@@ -90,6 +106,8 @@ impl Zoom {
         }
     }
 
+    /// Get this zoom value as a float value. Returns `None` if the value is the
+    /// `auto` keyword.
     #[inline]
     pub fn to_f32(&self) -> Option<f32> {
         match *self {