Add rust docs for rules

Author: devongovett

src/properties/grid.rs

@@ -74,7 +74,7 @@ impl Default for TrackSize {
 #[derive(Debug, Clone, PartialEq, Default)]
 pub struct TrackSizeList(pub SmallVec<[TrackSize; 1]>);
 
-/// A [`<track-breadth>`](https://drafts.csswg.org/css-grid-2/#typedef-track-breadth value.
+/// A [`<track-breadth>`](https://drafts.csswg.org/css-grid-2/#typedef-track-breadth) value.
 ///
 /// See [TrackSize](TrackSize).
 #[derive(Debug, Clone, PartialEq)]

src/properties/transform.rs

@@ -245,7 +245,7 @@ pub struct Matrix3d<T> {
   pub m44: T,
 }
 
-/// https://drafts.csswg.org/css-transforms-2/#mathematical-description
+// https://drafts.csswg.org/css-transforms-2/#mathematical-description
 impl Matrix3d<f32> {
   /// Creates an identity matrix.
   pub fn identity() -> Matrix3d<f32> {

src/rules/counter_style.rs

@@ -1,15 +1,21 @@
+//! The `@counter-style` rule.
+
 use super::Location;
 use crate::declaration::DeclarationBlock;
 use crate::error::PrinterError;
 use crate::printer::Printer;
 use crate::traits::ToCss;
 use crate::values::ident::CustomIdent;
 
+/// A [@counter-style](https://drafts.csswg.org/css-counter-styles/#the-counter-style-rule) rule.
 #[derive(Debug, PartialEq, Clone)]
 pub struct CounterStyleRule<'i> {
+  /// The name of the counter style to declare.
   pub name: CustomIdent<'i>,
   // TODO: eventually parse these properties
+  /// Declarations in the `@counter-style` rule.
   pub declarations: DeclarationBlock<'i>,
+  /// The location of the rule in the source file.
   pub loc: Location,
 }
 

src/rules/custom_media.rs

@@ -1,14 +1,20 @@
+//! The `@custom-media` rule.
+
 use super::Location;
 use crate::error::PrinterError;
 use crate::media_query::MediaList;
 use crate::printer::Printer;
 use crate::traits::ToCss;
 use crate::values::ident::DashedIdent;
 
+/// A [@custom-media](https://drafts.csswg.org/mediaqueries-5/#custom-mq) rule.
 #[derive(Debug, PartialEq, Clone)]
 pub struct CustomMediaRule<'i> {
+  /// The name of the declared media query.
   pub name: DashedIdent<'i>,
+  /// The media query to declare.
   pub query: MediaList<'i>,
+  /// The location of the rule in the source file.
   pub loc: Location,
 }
 

src/rules/document.rs

@@ -1,12 +1,20 @@
+//! The `@-moz-document` rule.
+
 use super::Location;
 use super::{CssRuleList, MinifyContext};
 use crate::error::{MinifyError, PrinterError};
 use crate::printer::Printer;
 use crate::traits::ToCss;
 
+/// A [@-moz-document](https://www.w3.org/TR/2012/WD-css3-conditional-20120911/#at-document) rule.
+///
+/// Note that only the `url-prefix()` function with no arguments is supported, and only the `-moz` prefix
+/// is allowed since Firefox was the only browser that ever implemented this rule.
 #[derive(Debug, PartialEq, Clone)]
 pub struct MozDocumentRule<'i> {
+  /// Nested rules within the `@-moz-document` rule.
   pub rules: CssRuleList<'i>,
+  /// The location of the rule in the source file.
   pub loc: Location,
 }
 

src/rules/font_face.rs

@@ -1,3 +1,5 @@
+//! The `@font-face` rule.
+
 use super::Location;
 use crate::error::{ParserError, PrinterError};
 use crate::macros::enum_property;
@@ -11,27 +13,43 @@ use crate::values::url::Url;
 use cssparser::*;
 use std::fmt::Write;
 
+/// A [@font-face](https://drafts.csswg.org/css-fonts/#font-face-rule) rule.
 #[derive(Debug, PartialEq, Clone)]
 pub struct FontFaceRule<'i> {
+  /// Declarations in the `@font-face` rule.
   pub properties: Vec<FontFaceProperty<'i>>,
+  /// The location of the rule in the source file.
   pub loc: Location,
 }
 
+/// A property within an `@font-face` rule.
+///
+/// See [FontFaceRule](FontFaceRule).
 #[derive(Debug, Clone, PartialEq)]
 pub enum FontFaceProperty<'i> {
+  /// The `src` property.
   Source(Vec<Source<'i>>),
+  /// The `font-family` property.
   FontFamily(FontFamily<'i>),
+  /// The `font-style` property.
   FontStyle(FontStyle),
+  /// The `font-weight` property.
   FontWeight(Size2D<FontWeight>),
+  /// The `font-stretch` property.
   FontStretch(Size2D<FontStretch>),
+  /// The `unicode-range` property.
   UnicodeRange(Vec<UnicodeRange>),
+  /// An unknown or unsupported property.
   Custom(CustomProperty<'i>),
 }
 
-/// https://www.w3.org/TR/2021/WD-css-fonts-4-20210729/#font-face-src-parsing
+/// A value for the [src](https://drafts.csswg.org/css-fonts/#src-desc)
+/// property in an `@font-face` rule.
 #[derive(Debug, Clone, PartialEq)]
 pub enum Source<'i> {
+  /// A `url()` with optional format metadata.
   Url(UrlSource<'i>),
+  /// The `local()` function.
   Local(FontFamily<'i>),
 }
 
@@ -63,9 +81,13 @@ impl<'i> ToCss for Source<'i> {
   }
 }
 
+/// A `url()` value for the [src](https://drafts.csswg.org/css-fonts/#src-desc)
+/// property in an `@font-face` rule.
 #[derive(Debug, Clone, PartialEq)]
 pub struct UrlSource<'i> {
+  /// The URL.
   pub url: Url<'i>,
+  /// Optional `format()` function.
   pub format: Option<Format<'i>>,
 }
 
@@ -99,9 +121,14 @@ impl<'i> ToCss for UrlSource<'i> {
   }
 }
 
+/// The `format()` function within the [src](https://drafts.csswg.org/css-fonts/#src-desc)
+/// property of an `@font-face` rule.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Format<'i> {
+  /// A font format name.
   pub format: FontFormat<'i>,
+  /// The `supports()` function.
+  // TODO: did this get renamed to `tech()`?
   pub supports: Vec<FontTechnology>,
 }
 
@@ -144,15 +171,26 @@ impl<'i> ToCss for Format<'i> {
   }
 }
 
+/// A font format keyword in the `format()` function of the the
+/// [src](https://drafts.csswg.org/css-fonts/#src-desc)
+/// property of an `@font-face` rule.
 #[derive(Debug, Clone, PartialEq)]
 pub enum FontFormat<'i> {
+  /// A WOFF font.
   WOFF,
+  /// A WOFF v2 font.
   WOFF2,
+  /// A TrueType font.
   TrueType,
+  /// An OpenType font.
   OpenType,
+  /// An Embedded OpenType (.eot) font.
   EmbeddedOpenType,
+  /// A font collection.
   Collection,
+  /// An SVG font.
   SVG,
+  /// An unknown format.
   String(CowArcStr<'i>),
 }
 
@@ -196,28 +234,49 @@ impl<'i> ToCss for FontFormat<'i> {
 }
 
 enum_property! {
+  /// A font feature tech descriptor in the `supports()`function of the
+  /// [src](https://drafts.csswg.org/css-fonts/#src-desc)
+  /// property of an `@font-face` rule.
   pub enum FontFeatureTechnology {
+    /// Supports OpenType features.
     OpenType,
+    /// Supports Apple Advanced Typography features.
     AAT,
+    /// Supports Graphite features.
     Graphite,
   }
 }
 
 enum_property! {
+  /// A color font tech descriptor in the `supports()`function of the
+  /// [src](https://drafts.csswg.org/css-fonts/#src-desc)
+  /// property of an `@font-face` rule.
   pub enum ColorFontTechnology {
+    /// Supports the `COLR` v0 table.
     COLRv0,
+    /// Supports the `COLR` v1 table.
     COLRv1,
+    /// Supports SVG glyphs.
     SVG,
+    /// Supports the `sbix` table.
     SBIX,
+    /// Supports the `CBDT` table.
     CBDT,
   }
 }
 
+/// A font technology descriptor in the `supports()`function of the
+/// [src](https://drafts.csswg.org/css-fonts/#src-desc)
+/// property of an `@font-face` rule.
 #[derive(Debug, Clone, PartialEq)]
 pub enum FontTechnology {
+  /// Supports font features.
   Features(FontFeatureTechnology),
+  /// Supports variations.
   Variations,
+  /// Supports color glyphs.
   Color(ColorFontTechnology),
+  /// Supports color palettes.
   Palettes,
 }
 

src/rules/font_palette_values.rs

@@ -1,3 +1,5 @@
+//! The `@font-palette-values` rule.
+
 use super::supports::SupportsRule;
 use super::{CssRule, CssRuleList, Location, MinifyContext};
 use crate::error::{ParserError, PrinterError};
@@ -11,34 +13,51 @@ use crate::values::ident::DashedIdent;
 use crate::values::number::CSSInteger;
 use cssparser::*;
 
-/// https://drafts.csswg.org/css-fonts-4/#font-palette-values
+/// A [@font-palette-values](https://drafts.csswg.org/css-fonts-4/#font-palette-values) rule.
 #[derive(Debug, PartialEq, Clone)]
 pub struct FontPaletteValuesRule<'i> {
+  /// The name of the font palette.
   pub name: DashedIdent<'i>,
+  /// Declarations in the `@font-palette-values` rule.
   pub properties: Vec<FontPaletteValuesProperty<'i>>,
+  /// The location of the rule in the source file.
   pub loc: Location,
 }
 
+/// A property within an `@font-palette-values` rule.
+///
+///  See [FontPaletteValuesRule](FontPaletteValuesRule).
 #[derive(Debug, Clone, PartialEq)]
 pub enum FontPaletteValuesProperty<'i> {
+  /// The `font-family` property.
   FontFamily(FontFamily<'i>),
+  /// The `base-palette` property.
   BasePalette(BasePalette),
+  /// The `override-colors` property.
   OverrideColors(Vec<OverrideColors>),
+  /// An unknown or unsupported property.
   Custom(CustomProperty<'i>),
 }
 
-/// https://drafts.csswg.org/css-fonts-4/#base-palette-desc
+/// A value for the [base-palette](https://drafts.csswg.org/css-fonts-4/#base-palette-desc)
+/// property in an `@font-palette-values` rule.
 #[derive(Debug, PartialEq, Clone)]
 pub enum BasePalette {
+  /// A light color palette as defined within the font.
   Light,
+  /// A dark color palette as defined within the font.
   Dark,
+  /// A palette index within the font.
   Integer(u16),
 }
 
-/// https://drafts.csswg.org/css-fonts-4/#override-color
+/// A value for the [override-colors](https://drafts.csswg.org/css-fonts-4/#override-color)
+/// property in an `@font-palette-values` rule.
 #[derive(Debug, PartialEq, Clone)]
 pub struct OverrideColors {
+  /// The index of the color within the palette to override.
   index: u16,
+  /// The replacement color.
   color: CssColor,
 }
 

src/rules/import.rs

@@ -1,3 +1,5 @@
+//! The `@import` rule.
+
 use super::layer::LayerName;
 use super::supports::SupportsCondition;
 use super::Location;
@@ -8,13 +10,18 @@ use crate::traits::ToCss;
 use crate::values::string::CowArcStr;
 use cssparser::*;
 
-/// https://drafts.csswg.org/css-cascade/#at-import
+/// A [@import](https://drafts.csswg.org/css-cascade/#at-import) rule.
 #[derive(Debug, PartialEq, Clone)]
 pub struct ImportRule<'i> {
+  /// The url to import.
   pub url: CowArcStr<'i>,
+  /// An optional cascade layer name, or `None` for an anonymous layer.
   pub layer: Option<Option<LayerName<'i>>>,
+  /// An optional `supports()` condition.
   pub supports: Option<SupportsCondition<'i>>,
+  /// A media query.
   pub media: MediaList<'i>,
+  /// The location of the rule in the source file.
   pub loc: Location,
 }
 

src/rules/keyframes.rs

@@ -1,3 +1,5 @@
+//! The `@keyframes` rule.
+
 use super::supports::SupportsRule;
 use super::MinifyContext;
 use super::{CssRule, CssRuleList, Location};
@@ -16,11 +18,16 @@ use crate::values::percentage::Percentage;
 use crate::vendor_prefix::VendorPrefix;
 use cssparser::*;
 
+/// A [@keyframes](https://drafts.csswg.org/css-animations/#keyframes) rule.
 #[derive(Debug, PartialEq, Clone)]
 pub struct KeyframesRule<'i> {
+  /// The animation name.
   pub name: CustomIdent<'i>,
+  /// A list of keyframes in the animation.
   pub keyframes: Vec<Keyframe<'i>>,
+  /// A vendor prefix for the rule, e.g. `@-webkit-keyframes`.
   pub vendor_prefix: VendorPrefix,
+  /// The location of the rule in the source file.
   pub loc: Location,
 }
 
@@ -173,11 +180,15 @@ impl<'i> ToCss for KeyframesRule<'i> {
   }
 }
 
-/// https://drafts.csswg.org/css-animations/#typedef-keyframe-selector
+/// A [keyframe selector](https://drafts.csswg.org/css-animations/#typedef-keyframe-selector)
+/// within an `@keyframes` rule.
 #[derive(Debug, PartialEq, Clone)]
 pub enum KeyframeSelector {
+  /// An explicit percentage.
   Percentage(Percentage),
+  /// The `from` keyword. Equivalent to 0%.
   From,
+  /// The `to` keyword. Equivalent to 100%.
   To,
 }
 
@@ -224,9 +235,14 @@ impl ToCss for KeyframeSelector {
   }
 }
 
+/// An individual keyframe within an `@keyframes` rule.
+///
+/// See [KeyframesRule](KeyframesRule).
 #[derive(Debug, PartialEq, Clone)]
 pub struct Keyframe<'i> {
+  /// A list of keyframe selectors to associate with the declarations in this keyframe.
   pub selectors: Vec<KeyframeSelector>,
+  /// The declarations for this keyframe.
   pub declarations: DeclarationBlock<'i>,
 }