codegen: Expose variant comments.

15 files changed, 220 insertions, 0 deletions

diff --git a/tests/expectations/tests/constify-enum.rs b/tests/expectations/tests/constify-enum.rs
index dd46e085..07279cf3 100644
--- a/tests/expectations/tests/constify-enum.rs
+++ b/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,
 }
diff --git a/tests/expectations/tests/enum-doc-bitfield.rs b/tests/expectations/tests/enum-doc-bitfield.rs
new file mode 100644
index 00000000..550286a2
--- /dev/null
+++ b/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);
diff --git a/tests/expectations/tests/enum-doc-mod.rs b/tests/expectations/tests/enum-doc-mod.rs
new file mode 100644
index 00000000..8cf7d323
--- /dev/null
+++ b/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;
+}
diff --git a/tests/expectations/tests/enum-doc-rusty.rs b/tests/expectations/tests/enum-doc-rusty.rs
new file mode 100644
index 00000000..9f47cc4b
--- /dev/null
+++ b/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,
+}
diff --git a/tests/expectations/tests/enum-doc.rs b/tests/expectations/tests/enum-doc.rs
new file mode 100644
index 00000000..8b552d29
--- /dev/null
+++ b/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;
diff --git a/tests/expectations/tests/jsval_layout_opaque.rs b/tests/expectations/tests/jsval_layout_opaque.rs
index 75945e7a..7e047f6a 100644
--- a/tests/expectations/tests/jsval_layout_opaque.rs
+++ b/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)]
diff --git a/tests/expectations/tests/jsval_layout_opaque_1_0.rs b/tests/expectations/tests/jsval_layout_opaque_1_0.rs
index 593c8f6f..29ce27ad 100644
--- a/tests/expectations/tests/jsval_layout_opaque_1_0.rs
+++ b/tests/expectations/tests/jsval_layout_opaque_1_0.rs
@@ -171,24 +171,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)]
diff --git a/tests/expectations/tests/layout_array_too_long.rs b/tests/expectations/tests/layout_array_too_long.rs
index 40f2fc5d..24ab41a4 100644
--- a/tests/expectations/tests/layout_array_too_long.rs
+++ b/tests/expectations/tests/layout_array_too_long.rs
@@ -11,8 +11,11 @@ pub const IP_MAX_FRAG_NUM: _bindgen_ty_1 = _bindgen_ty_1::IP_MAX_FRAG_NUM;
 #[repr(u32)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum _bindgen_ty_1 {
+    /// < index of last fragment
     IP_LAST_FRAG_IDX = 0,
+    /// < index of first fragment
     IP_FIRST_FRAG_IDX = 1,
+    /// < minimum number of fragments
     IP_MIN_FRAG_NUM = 2,
     IP_MAX_FRAG_NUM = 4,
 }
diff --git a/tests/expectations/tests/layout_eth_conf.rs b/tests/expectations/tests/layout_eth_conf.rs
index a06f62b0..71d03ef6 100644
--- a/tests/expectations/tests/layout_eth_conf.rs
+++ b/tests/expectations/tests/layout_eth_conf.rs
@@ -118,13 +118,21 @@ pub const RTE_ETH_FLOW_MAX: u32 = 22;
 /// packets to multiple queues.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_eth_rx_mq_mode {
+    /// None of DCB,RSS or VMDQ mode
     ETH_MQ_RX_NONE = 0,
+    /// For RX side, only RSS is on
     ETH_MQ_RX_RSS = 1,
+    /// For RX side,only DCB is on.
     ETH_MQ_RX_DCB = 2,
+    /// Both DCB and RSS enable
     ETH_MQ_RX_DCB_RSS = 3,
+    /// Only VMDQ, no RSS nor DCB
     ETH_MQ_RX_VMDQ_ONLY = 4,
+    /// RSS mode with VMDQ
     ETH_MQ_RX_VMDQ_RSS = 5,
+    /// Use VMDQ+DCB to route traffic to queues
     ETH_MQ_RX_VMDQ_DCB = 6,
+    /// Enable both VMDQ and DCB in VMDq
     ETH_MQ_RX_VMDQ_DCB_RSS = 7,
 }
 /// A structure used to configure the RX features of an Ethernet port.
@@ -345,9 +353,13 @@ impl rte_eth_rxmode {
 /// packets using multi-TCs.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_eth_tx_mq_mode {
+    /// < It is in neither DCB nor VT mode.
     ETH_MQ_TX_NONE = 0,
+    /// < For TX side,only DCB is on.
     ETH_MQ_TX_DCB = 1,
+    /// < For TX side,both DCB and VT is on.
     ETH_MQ_TX_VMDQ_DCB = 2,
+    /// < Only VT on, no DCB
     ETH_MQ_TX_VMDQ_ONLY = 3,
 }
 /// A structure used to configure the TX features of an Ethernet port.
@@ -534,7 +546,9 @@ impl Default for rte_eth_rss_conf {
 /// in DCB configratioins
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_eth_nb_tcs {
+    /// < 4 TCs with DCB.
     ETH_4_TCS = 4,
+    /// < 8 TCs with DCB.
     ETH_8_TCS = 8,
 }
 #[repr(u32)]
@@ -542,9 +556,13 @@ pub enum rte_eth_nb_tcs {
 /// in VMDQ configurations.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_eth_nb_pools {
+    /// < 8 VMDq pools.
     ETH_8_POOLS = 8,
+    /// < 16 VMDq pools.
     ETH_16_POOLS = 16,
+    /// < 32 VMDq pools.
     ETH_32_POOLS = 32,
+    /// < 64 VMDq pools.
     ETH_64_POOLS = 64,
 }
 /// A structure used to configure the VMDQ+DCB feature
@@ -1055,10 +1073,15 @@ impl Default for rte_eth_vmdq_rx_conf {
 /// Flow Director setting modes: none, signature or perfect.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_fdir_mode {
+    /// < Disable FDIR support.
     RTE_FDIR_MODE_NONE = 0,
+    /// < Enable FDIR signature filter mode.
     RTE_FDIR_MODE_SIGNATURE = 1,
+    /// < Enable FDIR perfect filter mode.
     RTE_FDIR_MODE_PERFECT = 2,
+    /// < Enable FDIR filter mode - MAC VLAN.
     RTE_FDIR_MODE_PERFECT_MAC_VLAN = 3,
+    /// < Enable FDIR filter mode - tunnel.
     RTE_FDIR_MODE_PERFECT_TUNNEL = 4,
 }
 #[repr(u32)]
@@ -1066,16 +1089,22 @@ pub enum rte_fdir_mode {
 /// in the board memory.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_fdir_pballoc_type {
+    /// < 64k.
     RTE_FDIR_PBALLOC_64K = 0,
+    /// < 128k.
     RTE_FDIR_PBALLOC_128K = 1,
+    /// < 256k.
     RTE_FDIR_PBALLOC_256K = 2,
 }
 #[repr(u32)]
 /// Select report mode of FDIR hash information in RX descriptors.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_fdir_status_mode {
+    /// < Never report FDIR hash.
     RTE_FDIR_NO_REPORT_STATUS = 0,
+    /// < Only report FDIR hash for matching pkts.
     RTE_FDIR_REPORT_STATUS = 1,
+    /// < Always report FDIR hash.
     RTE_FDIR_REPORT_STATUS_ALWAYS = 2,
 }
 /// A structure used to define the input for IPV4 flow
diff --git a/tests/expectations/tests/layout_eth_conf_1_0.rs b/tests/expectations/tests/layout_eth_conf_1_0.rs
index 5f614ca9..e9a09f54 100644
--- a/tests/expectations/tests/layout_eth_conf_1_0.rs
+++ b/tests/expectations/tests/layout_eth_conf_1_0.rs
@@ -161,13 +161,21 @@ pub const RTE_ETH_FLOW_MAX: u32 = 22;
 /// packets to multiple queues.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_eth_rx_mq_mode {
+    /// None of DCB,RSS or VMDQ mode
     ETH_MQ_RX_NONE = 0,
+    /// For RX side, only RSS is on
     ETH_MQ_RX_RSS = 1,
+    /// For RX side,only DCB is on.
     ETH_MQ_RX_DCB = 2,
+    /// Both DCB and RSS enable
     ETH_MQ_RX_DCB_RSS = 3,
+    /// Only VMDQ, no RSS nor DCB
     ETH_MQ_RX_VMDQ_ONLY = 4,
+    /// RSS mode with VMDQ
     ETH_MQ_RX_VMDQ_RSS = 5,
+    /// Use VMDQ+DCB to route traffic to queues
     ETH_MQ_RX_VMDQ_DCB = 6,
+    /// Enable both VMDQ and DCB in VMDq
     ETH_MQ_RX_VMDQ_DCB_RSS = 7,
 }
 /// A structure used to configure the RX features of an Ethernet port.
@@ -393,9 +401,13 @@ impl rte_eth_rxmode {
 /// packets using multi-TCs.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_eth_tx_mq_mode {
+    /// < It is in neither DCB nor VT mode.
     ETH_MQ_TX_NONE = 0,
+    /// < For TX side,only DCB is on.
     ETH_MQ_TX_DCB = 1,
+    /// < For TX side,both DCB and VT is on.
     ETH_MQ_TX_VMDQ_DCB = 2,
+    /// < Only VT on, no DCB
     ETH_MQ_TX_VMDQ_ONLY = 3,
 }
 /// A structure used to configure the TX features of an Ethernet port.
@@ -592,7 +604,9 @@ impl Default for rte_eth_rss_conf {
 /// in DCB configratioins
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_eth_nb_tcs {
+    /// < 4 TCs with DCB.
     ETH_4_TCS = 4,
+    /// < 8 TCs with DCB.
     ETH_8_TCS = 8,
 }
 #[repr(u32)]
@@ -600,9 +614,13 @@ pub enum rte_eth_nb_tcs {
 /// in VMDQ configurations.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_eth_nb_pools {
+    /// < 8 VMDq pools.
     ETH_8_POOLS = 8,
+    /// < 16 VMDq pools.
     ETH_16_POOLS = 16,
+    /// < 32 VMDq pools.
     ETH_32_POOLS = 32,
+    /// < 64 VMDq pools.
     ETH_64_POOLS = 64,
 }
 /// A structure used to configure the VMDQ+DCB feature
@@ -1153,10 +1171,15 @@ impl Default for rte_eth_vmdq_rx_conf {
 /// Flow Director setting modes: none, signature or perfect.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_fdir_mode {
+    /// < Disable FDIR support.
     RTE_FDIR_MODE_NONE = 0,
+    /// < Enable FDIR signature filter mode.
     RTE_FDIR_MODE_SIGNATURE = 1,
+    /// < Enable FDIR perfect filter mode.
     RTE_FDIR_MODE_PERFECT = 2,
+    /// < Enable FDIR filter mode - MAC VLAN.
     RTE_FDIR_MODE_PERFECT_MAC_VLAN = 3,
+    /// < Enable FDIR filter mode - tunnel.
     RTE_FDIR_MODE_PERFECT_TUNNEL = 4,
 }
 #[repr(u32)]
@@ -1164,16 +1187,22 @@ pub enum rte_fdir_mode {
 /// in the board memory.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_fdir_pballoc_type {
+    /// < 64k.
     RTE_FDIR_PBALLOC_64K = 0,
+    /// < 128k.
     RTE_FDIR_PBALLOC_128K = 1,
+    /// < 256k.
     RTE_FDIR_PBALLOC_256K = 2,
 }
 #[repr(u32)]
 /// Select report mode of FDIR hash information in RX descriptors.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum rte_fdir_status_mode {
+    /// < Never report FDIR hash.
     RTE_FDIR_NO_REPORT_STATUS = 0,
+    /// < Only report FDIR hash for matching pkts.
     RTE_FDIR_REPORT_STATUS = 1,
+    /// < Always report FDIR hash.
     RTE_FDIR_REPORT_STATUS_ALWAYS = 2,
 }
 /// A structure used to define the input for IPV4 flow
diff --git a/tests/expectations/tests/layout_large_align_field.rs b/tests/expectations/tests/layout_large_align_field.rs
index 15b7a4b7..af738d04 100644
--- a/tests/expectations/tests/layout_large_align_field.rs
+++ b/tests/expectations/tests/layout_large_align_field.rs
@@ -48,8 +48,11 @@ pub const IP_MAX_FRAG_NUM: _bindgen_ty_1 = _bindgen_ty_1::IP_MAX_FRAG_NUM;
 #[repr(u32)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
 pub enum _bindgen_ty_1 {
+    /// < index of last fragment
     IP_LAST_FRAG_IDX = 0,
+    /// < index of first fragment
     IP_FIRST_FRAG_IDX = 1,
+    /// < minimum number of fragments
     IP_MIN_FRAG_NUM = 2,
     IP_MAX_FRAG_NUM = 4,
 }
diff --git a/tests/headers/enum-doc-bitfield.h b/tests/headers/enum-doc-bitfield.h
new file mode 100644
index 00000000..5bbd7287
--- /dev/null
+++ b/tests/headers/enum-doc-bitfield.h
@@ -0,0 +1,3 @@
+// bindgen-flags: --bitfield-enum B
+
+#include "enum-doc.h"
diff --git a/tests/headers/enum-doc-mod.h b/tests/headers/enum-doc-mod.h
new file mode 100644
index 00000000..e5217451
--- /dev/null
+++ b/tests/headers/enum-doc-mod.h
@@ -0,0 +1,3 @@
+// bindgen-flags: --constified-enum-module B
+
+#include "enum-doc.h"
diff --git a/tests/headers/enum-doc-rusty.h b/tests/headers/enum-doc-rusty.h
new file mode 100644
index 00000000..35622d2b
--- /dev/null
+++ b/tests/headers/enum-doc-rusty.h
@@ -0,0 +1,3 @@
+// bindgen-flags: --rustified-enum B
+
+#include "enum-doc.h"
diff --git a/tests/headers/enum-doc.h b/tests/headers/enum-doc.h
new file mode 100644
index 00000000..53a91201
--- /dev/null
+++ b/tests/headers/enum-doc.h
@@ -0,0 +1,11 @@
+/** Document enum */
+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,
+    VAR_D = 3, /**< Document field with following star */
+    VAR_E = 4, /*!< Document field with following exclamation */
+};