Merge pull request #10 from wechat-miniprogram/feat-better-style-properties-docs

feat: better style properties docs

Author: LastLeaf

float-pigment-css-macro/src/property_list.rs

@@ -532,7 +532,7 @@ impl ToTokens for PropertiesDefinition {
                 cur_index += 1;
                 let invalid_ident =
                     Ident::new(&format!("Invalid{:X}", cur_index), enum_name.span());
-                enum_fields.push(quote!(#[serde(rename = "_")] #invalid_ident));
+                enum_fields.push(quote!(#[doc(hidden)] #[serde(rename = "_")] #invalid_ident));
             }
             cur_index += 1;
             enum_fields.push(quote! {

float-pigment-css-macro/src/style_syntax.rs

@@ -1,6 +1,7 @@
 use proc_macro2::TokenStream;
 use quote::*;
 use rustc_hash::FxHashMap;
+use std::fmt::Write;
 use std::ops::RangeInclusive;
 use syn::parse::*;
 use syn::punctuated::Punctuated;
@@ -737,10 +738,14 @@ impl Parse for StyleSyntaxDefinition {
 impl ToTokens for StyleSyntaxDefinition {
     fn to_tokens(&self, tokens: &mut TokenStream) {
         let Self { trait_name, items } = self;
+
+        // the parser functions
         let item_fn_list: Vec<_> = items.iter().map(|x| quote! { #x }).collect();
         tokens.append_all(quote! {
             #(#item_fn_list)*
         });
+
+        // the value parser mapping
         let map: Vec<_> = items
             .iter()
             .map(|item| {
@@ -846,6 +851,60 @@ impl ToTokens for StyleSyntaxDefinition {
                 Ok(false)
             }
         });
+
+        // the supported property list
+        let mut supported_properties: Vec<_> = items.iter().filter(|x| x.name.is_some()).collect();
+        supported_properties.sort_by(|a, b| {
+            let a = a.name.as_ref().unwrap();
+            let b = b.name.as_ref().unwrap();
+            a.cmp(b)
+        });
+        let supported_property_count = supported_properties.len();
+        let supported_property_names = supported_properties.iter().map(|x| x.name.as_ref().unwrap());
+        let mut style_doc = String::new();
+        writeln!(&mut style_doc, "The supported CSS property names.\n").unwrap();
+        writeln!(&mut style_doc, "This list is sorted, so it is safe to do binary search on it.\n").unwrap();
+        writeln!(&mut style_doc, "Note that this is just a simple list of basic parsing rules.\n").unwrap();
+        writeln!(&mut style_doc, "* Some properties in this list are shorthand properties that cannot be found in the [Property] enum.").unwrap();
+        writeln!(&mut style_doc, "* Parsing rules of some properties are slightly different from the web standard.").unwrap();
+        writeln!(&mut style_doc, "\nSee the table below for more information about all supported properties.\n").unwrap();
+        writeln!(&mut style_doc, "| Property Name | Related Property Variant | Major Value Options |").unwrap();
+        writeln!(&mut style_doc, "| ---- | ---- | ---- |").unwrap();
+        let table_list_a = supported_properties
+            .iter()
+            .filter(|x| !x.name.as_ref().unwrap().starts_with("-"));
+        let table_list_b = supported_properties
+            .iter()
+            .filter(|x| x.name.as_ref().unwrap().starts_with("-"));
+        for x in table_list_a.chain(table_list_b) {
+            let name = x.name.as_ref().unwrap();
+            let non_standard = name.starts_with("-");
+            let name_col = if non_standard { format!("*`{}`*", name) } else { format!("`{}`", name) };
+            let mut doc_col = String::new();
+            let mut options_col = vec![];
+            if let StyleSyntaxValueItem::Assign(variant, v) = &x.value {
+                doc_col = format!("[Property::{}]", variant);
+                if let StyleSyntaxValueItem::Branch(branches) = &**v {
+                    for item in branches {
+                        if let StyleSyntaxValueItem::Convert(v, _) = item {
+                            if let StyleSyntaxValueItem::MatchIdent(s) = &**v {
+                                options_col.push(format!("`{}`", s));
+                            }
+                        }
+                    }
+                }
+            }
+            options_col.sort();
+            writeln!(&mut style_doc, "| {} | {} | {} |", name_col, doc_col, options_col.join("<br>")).unwrap();
+        }
+        tokens.append_all(quote! {
+            #[doc = #style_doc]
+            pub const SUPPORTED_CSS_PROPERTY_NAMES: [&'static str; #supported_property_count] = [
+                #(
+                    #supported_property_names,
+                )*
+            ];
+        });
     }
 }
 

float-pigment-css-macro/src/value_type.rs

@@ -39,13 +39,14 @@ impl Parse for PropertyValueType {
                     Unset,
                     Var(Box<StrRef>),
                     VarInShorthand(Box<StrRef>, Box<StrRef>),
-                    Invalid0,
+                    #[doc(hidden)] Invalid0,
                 }
             "#;
             let mut new_variants = parse_str::<ItemEnum>(s)?.variants;
             for i in new_variants.len()..PRESERVE_GLOBAL_VALUE_RANGE {
                 let mut empty_slot = new_variants.last().unwrap().clone();
                 empty_slot.ident = Ident::new(&format!("Invalid{:X}", i), empty_slot.ident.span());
+                empty_slot.attrs.push(parse_quote!(#[doc(hidden)]));
                 new_variants.push(empty_slot);
             }
             new_variants

float-pigment-css/src/lib.rs

@@ -14,6 +14,14 @@
 //! 1. Merge the `MatchedRuleList` into `NodeProperties` with `MatchedRuleList::merge_node_properties`.
 //!
 //! The result `NodeProperties` contains all supported CSS properties.
+//! 
+//! ### Supported CSS Features
+//! 
+//! The supported selectors can be found in [StyleQuery] docs.
+//! 
+//! The supported media features can be found in [MediaQueryStatus] docs.
+//! 
+//! The supported style properties can be found in [SUPPORTED_CSS_PROPERTY_NAMES](crate::property::SUPPORTED_CSS_PROPERTY_NAMES) docs.
 //!
 //! ### The Binary Format
 //!