Bug 1519729 - Document public macros. r=emilio
authorSimon Sapin <simon.sapin@exyr.org>
Fri, 11 Jan 2019 14:03:44 +0100
changeset 453674 f63ebd7e9e281f22e71c268151337178de2c246a
parent 453673 4f2e84dc490dbbac2a35799b6b9230c105f2cd35
child 453675 a2f691714d70fa6a9119503270809fa0eb8df6c6
push id111121
push useremilio@crisal.io
push dateSun, 13 Jan 2019 20:57:57 +0000
treeherdermozilla-inbound@7ccafc4ab34c [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersemilio
bugs1519729, 22674
milestone66.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1519729 - Document public macros. r=emilio Undocumented public macros emit warnings in nightly-2019-01-11, and we #![deny] that warning. Cherry-picks a commit from https://github.com/servo/servo/pull/22674
servo/components/style/properties/properties.mako.rs
servo/components/style_traits/values.rs
--- a/servo/components/style/properties/properties.mako.rs
+++ b/servo/components/style/properties/properties.mako.rs
@@ -3816,17 +3816,24 @@ impl AliasId {
             AliasedPropertyId::Shorthand(ShorthandId::${alias.original.camel_case}),
             % endif
         % endfor
         ];
         MAP[self as usize]
     }
 }
 
-// NOTE(emilio): Callers are responsible to deal with prefs.
+/// Call the given macro with tokens like this for each longhand and shorthand properties
+/// that is enabled in content:
+///
+/// ```
+/// [CamelCaseName, SetCamelCaseName, PropertyId::Longhand(LonghandId::CamelCaseName)],
+/// ```
+///
+/// NOTE(emilio): Callers are responsible to deal with prefs.
 #[macro_export]
 macro_rules! css_properties_accessors {
     ($macro_name: ident) => {
         $macro_name! {
             % for kind, props in [("Longhand", data.longhands), ("Shorthand", data.shorthands)]:
                 % for property in props:
                     % if property.enabled_in_content():
                         % for prop in [property] + property.alias:
@@ -3839,16 +3846,24 @@ macro_rules! css_properties_accessors {
                         % endfor
                     % endif
                 % endfor
             % endfor
         }
     }
 }
 
+/// Call the given macro with tokens like this for each longhand properties:
+///
+/// ```
+/// { snake_case_ident, true }
+/// ```
+///
+/// … where the boolean indicates whether the property value type
+/// is wrapped in a `Box<_>` in the corresponding `PropertyDeclaration` variant.
 #[macro_export]
 macro_rules! longhand_properties_idents {
     ($macro_name: ident) => {
         $macro_name! {
             % for property in data.longhands:
                 { ${property.ident}, ${"true" if property.boxed else "false"} }
             % endfor
         }
--- a/servo/components/style_traits/values.rs
+++ b/servo/components/style_traits/values.rs
@@ -427,17 +427,17 @@ impl_to_css_for_predefined_type!(i8);
 impl_to_css_for_predefined_type!(i32);
 impl_to_css_for_predefined_type!(u16);
 impl_to_css_for_predefined_type!(u32);
 impl_to_css_for_predefined_type!(::cssparser::Token<'a>);
 impl_to_css_for_predefined_type!(::cssparser::RGBA);
 impl_to_css_for_predefined_type!(::cssparser::Color);
 impl_to_css_for_predefined_type!(::cssparser::UnicodeRange);
 
-#[macro_export]
+/// Define an enum type with unit variants that each corrsepond to a CSS keyword.
 macro_rules! define_css_keyword_enum {
     (pub enum $name:ident { $($variant:ident = $css:expr,)+ }) => {
         #[allow(missing_docs)]
         #[cfg_attr(feature = "servo", derive(Deserialize, Serialize))]
         #[derive(Clone, Copy, Debug, Eq, Hash, MallocSizeOf, PartialEq)]
         pub enum $name {
             $($variant),+
         }