codegen: Expose variant comments.

Author: emilio

src/codegen/mod.rs

@@ -2129,36 +2129,54 @@ impl EnumVariation {
 /// A helper type to construct different enum variations.
 enum EnumBuilder<'a> {
     Rust {
+        codegen_depth: usize,
         attrs: Vec<quote::Tokens>,
         ident: proc_macro2::Term,
         tokens: quote::Tokens,
         emitted_any_variants: bool,
     },
     Bitfield {
+        codegen_depth: usize,
         canonical_name: &'a str,
         tokens: quote::Tokens,
     },
-    Consts(Vec<quote::Tokens>),
+    Consts {
+        variants: Vec<quote::Tokens>,
+        codegen_depth: usize,
+    },
     ModuleConsts {
+        codegen_depth: usize,
         module_name: &'a str,
         module_items: Vec<quote::Tokens>,
     },
 }
 
 impl<'a> EnumBuilder<'a> {
+    /// Returns the depth of the code generation for a variant of this enum.
+    fn codegen_depth(&self) -> usize {
+        match *self {
+            EnumBuilder::Rust { codegen_depth, .. } |
+            EnumBuilder::Bitfield { codegen_depth, .. } |
+            EnumBuilder::ModuleConsts { codegen_depth, .. } |
+            EnumBuilder::Consts { codegen_depth, .. } => codegen_depth,
+        }
+    }
+
     /// Create a new enum given an item builder, a canonical name, a name for
     /// the representation, and which variation it should be generated as.
     fn new(
         name: &'a str,
         attrs: Vec<quote::Tokens>,
         repr: quote::Tokens,
-        enum_variation: EnumVariation
+        enum_variation: EnumVariation,
+        enum_codegen_depth: usize,
     ) -> Self {
         let ident = proc_macro2::Term::intern(name);
 
         match enum_variation {
             EnumVariation::Bitfield => {
                 EnumBuilder::Bitfield {
+                    codegen_depth: enum_codegen_depth,
                     canonical_name: name,
                     tokens: quote! {
                         #( #attrs )*
@@ -2170,6 +2188,7 @@ impl<'a> EnumBuilder<'a> {
             EnumVariation::Rust => {
                 let tokens = quote!();
                 EnumBuilder::Rust {
+                    codegen_depth: enum_codegen_depth + 1,
                     attrs,
                     ident,
                     tokens,
@@ -2178,20 +2197,26 @@ impl<'a> EnumBuilder<'a> {
             }
 
             EnumVariation::Consts => {
-                EnumBuilder::Consts(vec![
-                    quote! {
-                        pub type #ident = #repr;
-                    }
-                ])
+                EnumBuilder::Consts {
+                    variants: vec![
+                        quote! {
+                            #( #attrs )*
+                            pub type #ident = #repr;
+                        }
+                    ],
+                    codegen_depth: enum_codegen_depth,
+                }
             }
 
             EnumVariation::ModuleConsts => {
                 let ident = proc_macro2::Term::intern(CONSTIFIED_ENUM_MODULE_REPR_NAME);
                 let type_definition = quote! {
+                    #( #attrs )*
                     pub type #ident = #repr;
                 };
 
                 EnumBuilder::ModuleConsts {
+                    codegen_depth: enum_codegen_depth + 1,
                     module_name: name,
                     module_items: vec![type_definition],
                 }
@@ -2214,14 +2239,24 @@ impl<'a> EnumBuilder<'a> {
             EnumVariantValue::Unsigned(v) => helpers::ast_ty::uint_expr(v),
         };
 
+        let mut doc = quote! {};
+        if ctx.options().generate_comments {
+            if let Some(raw_comment) = variant.comment() {
+                let comment = comment::preprocess(raw_comment, self.codegen_depth());
+                doc = attributes::doc(comment);
+            }
+        }
+
         match self {
-            EnumBuilder::Rust { attrs, ident, tokens, emitted_any_variants: _ } => {
+            EnumBuilder::Rust { attrs, ident, tokens, emitted_any_variants: _, codegen_depth } => {
                 let name = ctx.rust_ident(variant_name);
                 EnumBuilder::Rust {
                     attrs,
                     ident,
+                    codegen_depth,
                     tokens: quote! {
                         #tokens
+                        #doc
                         #name = #expr,
                     },
                     emitted_any_variants: true,
@@ -2238,6 +2273,7 @@ impl<'a> EnumBuilder<'a> {
 
                 let ident = ctx.rust_ident(constant_name);
                 result.push(quote! {
+                    #doc
                     pub const #ident : #rust_ty = #rust_ty ( #expr );
                 });
 
@@ -2256,24 +2292,28 @@ impl<'a> EnumBuilder<'a> {
 
                 let ident = ctx.rust_ident(constant_name);
                 result.push(quote! {
+                    #doc
                     pub const #ident : #rust_ty = #expr ;
                 });
 
                 self
             }
             EnumBuilder::ModuleConsts {
+                codegen_depth,
                 module_name,
                 mut module_items,
             } => {
                 let name = ctx.rust_ident(variant_name);
                 let ty = ctx.rust_ident(CONSTIFIED_ENUM_MODULE_REPR_NAME);
                 module_items.push(quote! {
+                    #doc
                     pub const #name : #ty = #expr ;
                 });
 
                 EnumBuilder::ModuleConsts {
                     module_name,
                     module_items,
+                    codegen_depth,
                 }
             }
         }
@@ -2286,23 +2326,24 @@ impl<'a> EnumBuilder<'a> {
         result: &mut CodegenResult<'b>,
     ) -> quote::Tokens {
         match self {
-            EnumBuilder::Rust { attrs, ident, tokens, emitted_any_variants } => {
+            EnumBuilder::Rust { attrs, ident, tokens, emitted_any_variants, .. } => {
                 let variants = if !emitted_any_variants {
                     quote!(__bindgen_cannot_repr_c_on_empty_enum = 0)
                 } else {
                     tokens
                 };
 
-                quote! (
+                quote! {
                     #( #attrs )*
                     pub enum #ident {
                         #variants
                     }
-                )
+                }
             }
             EnumBuilder::Bitfield {
                 canonical_name,
                 tokens,
+                ..
             } => {
                 let rust_ty_name = ctx.rust_ident_raw(canonical_name);
                 let prefix = ctx.trait_prefix();
@@ -2349,10 +2390,11 @@ impl<'a> EnumBuilder<'a> {
 
                 tokens
             }
-            EnumBuilder::Consts(tokens) => quote! { #( #tokens )* },
+            EnumBuilder::Consts { variants, .. } => quote! { #( #variants )* },
             EnumBuilder::ModuleConsts {
                 module_items,
                 module_name,
+                ..
             } => {
                 let ident = ctx.rust_ident(module_name);
                 quote! {
@@ -2489,7 +2531,8 @@ impl CodeGenerator for Enum {
             &name,
             attrs,
             repr,
-            variation
+            variation,
+            item.codegen_depth(ctx),
         );
 
         // A map where we keep a value -> variant relation.
@@ -2522,8 +2565,7 @@ impl CodeGenerator for Enum {
         let mut iter = self.variants().iter().peekable();
         while let Some(variant) = iter.next().or_else(|| {
             constified_variants.pop_front()
-        })
-        {
+        }) {
             if variant.hidden() {
                 continue;
             }

src/ir/enum_ty.rs

@@ -221,6 +221,11 @@ impl EnumVariant {
         self.val
     }
 
+    /// Get this variant's documentation.
+    pub fn comment(&self) -> Option<&str> {
+        self.comment.as_ref().map(|s| &**s)
+    }
+
     /// Returns whether this variant should be enforced to be a constant by code
     /// generation.
     pub fn force_constification(&self) -> bool {

tests/expectations/tests/constify-enum.rs

@@ -13,5 +13,6 @@ pub enum nsCSSPropertyID {
     eCSSProperty_b = 1,
     eCSSPropertyAlias_aa = 2,
     eCSSPropertyAlias_bb = 3,
+    /// < <div rustbindgen constant></div>
     eCSSProperty_COUNT_unexistingVariantValue = 4,
 }

tests/expectations/tests/enum-doc-bitfield.rs

@@ -0,0 +1,44 @@
+/* automatically generated by rust-bindgen */
+
+#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
+
+/// Document field with three slashes
+pub const B_VAR_A: B = B(0);
+/// Document field with preceeding star
+pub const B_VAR_B: B = B(1);
+/// Document field with preceeding exclamation
+pub const B_VAR_C: B = B(2);
+/// < Document field with following star
+pub const B_VAR_D: B = B(3);
+/// < Document field with following exclamation
+pub const B_VAR_E: B = B(4);
+impl ::std::ops::BitOr<B> for B {
+    type Output = Self;
+    #[inline]
+    fn bitor(self, other: Self) -> Self {
+        B(self.0 | other.0)
+    }
+}
+impl ::std::ops::BitOrAssign for B {
+    #[inline]
+    fn bitor_assign(&mut self, rhs: B) {
+        self.0 |= rhs.0;
+    }
+}
+impl ::std::ops::BitAnd<B> for B {
+    type Output = Self;
+    #[inline]
+    fn bitand(self, other: Self) -> Self {
+        B(self.0 & other.0)
+    }
+}
+impl ::std::ops::BitAndAssign for B {
+    #[inline]
+    fn bitand_assign(&mut self, rhs: B) {
+        self.0 &= rhs.0;
+    }
+}
+#[repr(C)]
+/// Document enum
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
+pub struct B(pub u32);

tests/expectations/tests/enum-doc-mod.rs

@@ -0,0 +1,18 @@
+/* automatically generated by rust-bindgen */
+
+#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
+
+pub mod B {
+    /// Document enum
+    pub type Type = u32;
+    /// Document field with three slashes
+    pub const VAR_A: Type = 0;
+    /// Document field with preceeding star
+    pub const VAR_B: Type = 1;
+    /// Document field with preceeding exclamation
+    pub const VAR_C: Type = 2;
+    /// < Document field with following star
+    pub const VAR_D: Type = 3;
+    /// < Document field with following exclamation
+    pub const VAR_E: Type = 4;
+}

tests/expectations/tests/enum-doc-rusty.rs

@@ -0,0 +1,19 @@
+/* automatically generated by rust-bindgen */
+
+#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
+
+#[repr(u32)]
+/// Document enum
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
+pub enum B {
+    /// Document field with three slashes
+    VAR_A = 0,
+    /// Document field with preceeding star
+    VAR_B = 1,
+    /// Document field with preceeding exclamation
+    VAR_C = 2,
+    /// < Document field with following star
+    VAR_D = 3,
+    /// < Document field with following exclamation
+    VAR_E = 4,
+}

tests/expectations/tests/enum-doc.rs

@@ -0,0 +1,16 @@
+/* automatically generated by rust-bindgen */
+
+#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
+
+/// Document field with three slashes
+pub const B_VAR_A: B = 0;
+/// Document field with preceeding star
+pub const B_VAR_B: B = 1;
+/// Document field with preceeding exclamation
+pub const B_VAR_C: B = 2;
+/// < Document field with following star
+pub const B_VAR_D: B = 3;
+/// < Document field with following exclamation
+pub const B_VAR_E: B = 4;
+/// Document enum
+pub type B = u32;

tests/expectations/tests/jsval_layout_opaque.rs

@@ -128,24 +128,43 @@ pub enum JSValueShiftedTag {
 #[repr(u32)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum JSWhyMagic {
+    /// a hole in a native object's elements
     JS_ELEMENTS_HOLE = 0,
+    /// there is not a pending iterator value
     JS_NO_ITER_VALUE = 1,
+    /// exception value thrown when closing a generator
     JS_GENERATOR_CLOSING = 2,
+    /// compiler sentinel value
     JS_NO_CONSTANT = 3,
+    /// used in debug builds to catch tracing errors
     JS_THIS_POISON = 4,
+    /// used in debug builds to catch tracing errors
     JS_ARG_POISON = 5,
+    /// an empty subnode in the AST serializer
     JS_SERIALIZE_NO_NODE = 6,
+    /// lazy arguments value on the stack
     JS_LAZY_ARGUMENTS = 7,
+    /// optimized-away 'arguments' value
     JS_OPTIMIZED_ARGUMENTS = 8,
+    /// magic value passed to natives to indicate construction
     JS_IS_CONSTRUCTING = 9,
+    /// arguments.callee has been overwritten
     JS_OVERWRITTEN_CALLEE = 10,
+    /// value of static block object slot
     JS_BLOCK_NEEDS_CLONE = 11,
+    /// see class js::HashableValue
     JS_HASH_KEY_EMPTY = 12,
+    /// error while running Ion code
     JS_ION_ERROR = 13,
+    /// missing recover instruction result
     JS_ION_BAILOUT = 14,
+    /// optimized out slot
     JS_OPTIMIZED_OUT = 15,
+    /// uninitialized lexical bindings that produce ReferenceError on touch.
     JS_UNINITIALIZED_LEXICAL = 16,
+    /// for local use
     JS_GENERIC_MAGIC = 17,
+    /// for local use
     JS_WHY_MAGIC_COUNT = 18,
 }
 #[repr(C)]