From b4e1946f772b105ef44229bf7c10cf1b02ce79f8 Mon Sep 17 00:00:00 2001
From: Jonathan Schwender <schwenderjonathan@gmail.com>
Date: Wed, 5 Feb 2025 14:37:39 +0100
Subject: [PATCH] Fix multiline doc comments

Fixes #3073
---
 .../tests/array-of-zero-sized-types.rs        |   4 +-
 .../expectations/tests/attribute-custom.rs    |   4 +-
 .../expectations/tests/comment-indent.rs      |  36 ++---
 .../tests/contains-vs-inherits-zero-sized.rs  |   8 +-
 .../tests/derive-bitfield-method-same-name.rs |   6 +-
 .../tests/expectations/tests/derive-custom.rs |   4 +-
 .../tests/derive-default-and-blocklist.rs     |   4 +-
 .../tests/derive-hash-blocklisting.rs         |   4 +-
 .../tests/derive-partialeq-and-blocklist.rs   |   4 +-
 .../tests/expectations/tests/doggo-or-null.rs |  12 +-
 .../tests/dynamic_loading_attributes.rs       |  10 +-
 .../expectations/tests/enum-doc-bitfield.rs   |   8 +-
 .../tests/expectations/tests/enum-doc-mod.rs  |   8 +-
 .../expectations/tests/enum-doc-rusty.rs      |   8 +-
 .../tests/expectations/tests/enum-doc.rs      |   8 +-
 .../tests/enum-variant-replaces.rs            |  12 +-
 .../tests/expectations/tests/issue-1995.rs    |  12 +-
 .../tests/issue-537-repr-packed-n.rs          |  10 +-
 .../tests/expectations/tests/issue-537.rs     |  20 +--
 .../issue-648-derive-debug-with-padding.rs    |  12 +-
 .../issue-848-replacement-system-include.rs   |  12 +-
 .../tests/expectations/tests/layout_arp.rs    |  18 +--
 .../tests/expectations/tests/layout_array.rs  |  30 ++--
 .../tests/layout_array_too_long.rs            |   4 +-
 .../tests/layout_cmdline_token.rs             |  42 +++---
 .../expectations/tests/layout_eth_conf.rs     | 134 +++++++++---------
 .../tests/layout_large_align_field.rs         |   4 +-
 .../tests/expectations/tests/layout_mbuf.rs   |  16 +--
 .../expectations/tests/no-derive-debug.rs     |   6 +-
 .../expectations/tests/no-derive-default.rs   |   6 +-
 .../tests/opaque-template-inst-member-2.rs    |   4 +-
 .../tests/opaque-template-inst-member.rs      |   8 +-
 .../tests/replace_template_alias.rs           |   6 +-
 .../tests/expectations/tests/template.rs      |  16 +--
 .../tests/templatized-bitfield.rs             |   6 +-
 .../expectations/tests/zero-sized-array.rs    |   4 +-
 bindgen/codegen/helpers.rs                    |   4 +-
 37 files changed, 258 insertions(+), 256 deletions(-)

diff --git a/bindgen-tests/tests/expectations/tests/array-of-zero-sized-types.rs b/bindgen-tests/tests/expectations/tests/array-of-zero-sized-types.rs
index 4630abd275..90970372a9 100644
--- a/bindgen-tests/tests/expectations/tests/array-of-zero-sized-types.rs
+++ b/bindgen-tests/tests/expectations/tests/array-of-zero-sized-types.rs
@@ -10,8 +10,8 @@ const _: () = {
     ["Size of Empty"][::std::mem::size_of::<Empty>() - 1usize];
     ["Alignment of Empty"][::std::mem::align_of::<Empty>() - 1usize];
 };
-/** This should not get an `_address` byte, since each `Empty` gets one, meaning
- that this object is addressable.*/
+/// This should not get an `_address` byte, since each `Empty` gets one, meaning
+/// that this object is addressable.
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct HasArrayOfEmpty {
diff --git a/bindgen-tests/tests/expectations/tests/attribute-custom.rs b/bindgen-tests/tests/expectations/tests/attribute-custom.rs
index 6d616d3f3e..b90f9ee676 100644
--- a/bindgen-tests/tests/expectations/tests/attribute-custom.rs
+++ b/bindgen-tests/tests/expectations/tests/attribute-custom.rs
@@ -5,8 +5,8 @@
 pub struct my_type {
     pub a: ::std::os::raw::c_int,
 }
-/** <div rustbindgen attribute="#[derive(Debug)]"></div>
- <div rustbindgen attribute="#[derive(Clone)]"></div>*/
+/// <div rustbindgen attribute="#[derive(Debug)]"></div>
+/// <div rustbindgen attribute="#[derive(Clone)]"></div>
 #[repr(C)]
 #[derive(Debug)]
 #[derive(Clone)]
diff --git a/bindgen-tests/tests/expectations/tests/comment-indent.rs b/bindgen-tests/tests/expectations/tests/comment-indent.rs
index 72b167d00c..76a19d8221 100644
--- a/bindgen-tests/tests/expectations/tests/comment-indent.rs
+++ b/bindgen-tests/tests/expectations/tests/comment-indent.rs
@@ -3,17 +3,17 @@
 pub mod root {
     #[allow(unused_imports)]
     use self::super::root;
-    /** This is a multi-line doc comment.
-
- This class is really really interesting, look!*/
+    /// This is a multi-line doc comment.
+    ///
+    /// This class is really really interesting, look!
     #[repr(C)]
     #[derive(Debug, Default, Copy, Clone)]
     pub struct Foo {
         pub _address: u8,
     }
-    /** This nested class is also a multi-line doc comment.
-
- This class is not so interesting, but worth a bit of docs too!*/
+    /// This nested class is also a multi-line doc comment.
+    ///
+    /// This class is not so interesting, but worth a bit of docs too!
     #[repr(C)]
     #[derive(Debug, Default, Copy, Clone)]
     pub struct Foo_Bar {
@@ -32,18 +32,18 @@ pub mod root {
     pub mod test {
         #[allow(unused_imports)]
         use self::super::super::root;
-        /** I'm in a namespace, and thus I may be on a rust module, most of the time.
- My documentation is pretty extensive, I guess.*/
+        /// I'm in a namespace, and thus I may be on a rust module, most of the time.
+        /// My documentation is pretty extensive, I guess.
         #[repr(C)]
         #[derive(Debug, Default, Copy, Clone)]
         pub struct Baz {
-            /** This member is plain awesome, just amazing.
-
- It also has super-extensive docs, with even a nice ascii-art diagram.
-
- +------+          +-------+
- | foo  |   ---->  | bar   |
- +------+          +-------+*/
+            /// This member is plain awesome, just amazing.
+            ///
+            /// It also has super-extensive docs, with even a nice ascii-art diagram.
+            ///
+            /// +------+          +-------+
+            /// | foo  |   ---->  | bar   |
+            /// +------+          +-------+
             pub member: ::std::os::raw::c_int,
         }
         #[allow(clippy::unnecessary_operation, clippy::identity_op)]
@@ -54,9 +54,9 @@ pub mod root {
                 "Offset of field: Baz::member",
             ][::std::mem::offset_of!(Baz, member) - 0usize];
         };
-        /** I'm in an inline namespace, and as such I shouldn't get generated inside
- a rust module, except when the relevant option is specified. Also, this
- comment shouldn't be misaligned.*/
+        /// I'm in an inline namespace, and as such I shouldn't get generated inside
+        /// a rust module, except when the relevant option is specified. Also, this
+        /// comment shouldn't be misaligned.
         #[repr(C)]
         #[derive(Debug, Default, Copy, Clone)]
         pub struct InInlineNS {
diff --git a/bindgen-tests/tests/expectations/tests/contains-vs-inherits-zero-sized.rs b/bindgen-tests/tests/expectations/tests/contains-vs-inherits-zero-sized.rs
index 3362280843..63d18a051a 100644
--- a/bindgen-tests/tests/expectations/tests/contains-vs-inherits-zero-sized.rs
+++ b/bindgen-tests/tests/expectations/tests/contains-vs-inherits-zero-sized.rs
@@ -10,8 +10,8 @@ const _: () = {
     ["Size of Empty"][::std::mem::size_of::<Empty>() - 1usize];
     ["Alignment of Empty"][::std::mem::align_of::<Empty>() - 1usize];
 };
-/** This should not get an `_address` byte, so `sizeof(Inherits)` should be
- `1`.*/
+/// This should not get an `_address` byte, so `sizeof(Inherits)` should be
+/// `1`.
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct Inherits {
@@ -23,8 +23,8 @@ const _: () = {
     ["Alignment of Inherits"][::std::mem::align_of::<Inherits>() - 1usize];
     ["Offset of field: Inherits::b"][::std::mem::offset_of!(Inherits, b) - 0usize];
 };
-/** This should not get an `_address` byte, but contains `Empty` which *does* get
- one, so `sizeof(Contains)` should be `1 + 1`.*/
+/// This should not get an `_address` byte, but contains `Empty` which *does* get
+/// one, so `sizeof(Contains)` should be `1 + 1`.
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct Contains {
diff --git a/bindgen-tests/tests/expectations/tests/derive-bitfield-method-same-name.rs b/bindgen-tests/tests/expectations/tests/derive-bitfield-method-same-name.rs
index 05e66a72bc..393b278673 100644
--- a/bindgen-tests/tests/expectations/tests/derive-bitfield-method-same-name.rs
+++ b/bindgen-tests/tests/expectations/tests/derive-bitfield-method-same-name.rs
@@ -87,9 +87,9 @@ where
         }
     }
 }
-/** Because this struct have array larger than 32 items
- and --with-derive-partialeq --impl-partialeq --impl-debug is provided,
- this struct should manually implement `Debug` and `PartialEq`.*/
+/// Because this struct have array larger than 32 items
+/// and --with-derive-partialeq --impl-partialeq --impl-debug is provided,
+/// this struct should manually implement `Debug` and `PartialEq`.
 #[repr(C)]
 #[derive(Copy, Clone)]
 pub struct Foo {
diff --git a/bindgen-tests/tests/expectations/tests/derive-custom.rs b/bindgen-tests/tests/expectations/tests/derive-custom.rs
index 9a69ebbb73..d52fd3a8ef 100644
--- a/bindgen-tests/tests/expectations/tests/derive-custom.rs
+++ b/bindgen-tests/tests/expectations/tests/derive-custom.rs
@@ -5,8 +5,8 @@
 pub struct my_type {
     pub a: ::std::os::raw::c_int,
 }
-/** <div rustbindgen derive="Debug"></div>
- <div rustbindgen derive="Clone"></div>*/
+/// <div rustbindgen derive="Debug"></div>
+/// <div rustbindgen derive="Clone"></div>
 #[repr(C)]
 #[derive(Default, Debug, Clone)]
 pub struct my_type2 {
diff --git a/bindgen-tests/tests/expectations/tests/derive-default-and-blocklist.rs b/bindgen-tests/tests/expectations/tests/derive-default-and-blocklist.rs
index 6ce99e5093..3cd64455ce 100644
--- a/bindgen-tests/tests/expectations/tests/derive-default-and-blocklist.rs
+++ b/bindgen-tests/tests/expectations/tests/derive-default-and-blocklist.rs
@@ -1,7 +1,7 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
 pub struct BlocklistMe(u8);
-/** Because this type contains a blocklisted type, it should not derive
- Default. Instead, we should emit a `mem::zeroed` implementation.*/
+/// Because this type contains a blocklisted type, it should not derive
+/// Default. Instead, we should emit a `mem::zeroed` implementation.
 #[repr(C)]
 pub struct ShouldNotDeriveDefault {
     pub a: BlocklistMe,
diff --git a/bindgen-tests/tests/expectations/tests/derive-hash-blocklisting.rs b/bindgen-tests/tests/expectations/tests/derive-hash-blocklisting.rs
index e3223f08d7..f58d0eb03f 100644
--- a/bindgen-tests/tests/expectations/tests/derive-hash-blocklisting.rs
+++ b/bindgen-tests/tests/expectations/tests/derive-hash-blocklisting.rs
@@ -5,8 +5,8 @@ pub struct Blocklisted<T> {
     t: T,
     pub _phantom_0: ::std::marker::PhantomData<::std::cell::UnsafeCell<T>>,
 }
-/** This would derive(Hash, Eq, PartialEq) if it didn't contain a blocklisted type,
- causing us to conservatively avoid deriving hash/Eq/PartialEq for it.*/
+/// This would derive(Hash, Eq, PartialEq) if it didn't contain a blocklisted type,
+/// causing us to conservatively avoid deriving hash/Eq/PartialEq for it.
 #[repr(C)]
 pub struct AllowlistedOne {
     pub a: Blocklisted<::std::os::raw::c_int>,
diff --git a/bindgen-tests/tests/expectations/tests/derive-partialeq-and-blocklist.rs b/bindgen-tests/tests/expectations/tests/derive-partialeq-and-blocklist.rs
index d24981061c..6587473141 100644
--- a/bindgen-tests/tests/expectations/tests/derive-partialeq-and-blocklist.rs
+++ b/bindgen-tests/tests/expectations/tests/derive-partialeq-and-blocklist.rs
@@ -1,7 +1,7 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
 pub struct BlocklistMe(u8);
-/** Because this type contains a blocklisted type, it should not derive
- PartialEq.*/
+/// Because this type contains a blocklisted type, it should not derive
+/// PartialEq.
 #[repr(C)]
 pub struct ShouldNotDerivePartialEq {
     pub a: BlocklistMe,
diff --git a/bindgen-tests/tests/expectations/tests/doggo-or-null.rs b/bindgen-tests/tests/expectations/tests/doggo-or-null.rs
index 972da871d3..c404fa7b82 100644
--- a/bindgen-tests/tests/expectations/tests/doggo-or-null.rs
+++ b/bindgen-tests/tests/expectations/tests/doggo-or-null.rs
@@ -20,12 +20,12 @@ const _: () = {
     ["Size of Null"][::std::mem::size_of::<Null>() - 1usize];
     ["Alignment of Null"][::std::mem::align_of::<Null>() - 1usize];
 };
-/** This type is an opaque union. Unions can't derive anything interesting like
- Debug or Default, even if their layout can, because it would require knowing
- which variant is in use. Opaque unions still end up as a `union` in the Rust
- bindings, but they just have one variant. Even so, can't derive. We should
- probably emit an opaque struct for opaque unions... but until then, we have
- this test to make sure that opaque unions don't derive and still compile.*/
+/// This type is an opaque union. Unions can't derive anything interesting like
+/// Debug or Default, even if their layout can, because it would require knowing
+/// which variant is in use. Opaque unions still end up as a `union` in the Rust
+/// bindings, but they just have one variant. Even so, can't derive. We should
+/// probably emit an opaque struct for opaque unions... but until then, we have
+/// this test to make sure that opaque unions don't derive and still compile.
 #[repr(C)]
 #[repr(align(4))]
 #[derive(Copy, Clone)]
diff --git a/bindgen-tests/tests/expectations/tests/dynamic_loading_attributes.rs b/bindgen-tests/tests/expectations/tests/dynamic_loading_attributes.rs
index a1fb1b0cc1..d22e64841c 100644
--- a/bindgen-tests/tests/expectations/tests/dynamic_loading_attributes.rs
+++ b/bindgen-tests/tests/expectations/tests/dynamic_loading_attributes.rs
@@ -25,11 +25,11 @@ impl TestLib {
         Ok(TestLib { __library, foo, baz })
     }
     #[must_use]
-    /** @brief A function
-
- @param x
- @param y
- @return int*/
+    /// @brief A function
+    ///
+    /// @param x
+    /// @param y
+    /// @return int
     pub unsafe fn foo(
         &self,
         x: ::std::os::raw::c_int,
diff --git a/bindgen-tests/tests/expectations/tests/enum-doc-bitfield.rs b/bindgen-tests/tests/expectations/tests/enum-doc-bitfield.rs
index ba73a8ea3e..20fc976b5d 100644
--- a/bindgen-tests/tests/expectations/tests/enum-doc-bitfield.rs
+++ b/bindgen-tests/tests/expectations/tests/enum-doc-bitfield.rs
@@ -20,10 +20,10 @@ impl B {
     pub const VAR_E: B = B(4);
 }
 impl B {
-    /** Document field with preceding star, with a loong long multiline
- comment.
-
- Very interesting documentation, definitely.*/
+    /// Document field with preceding star, with a loong long multiline
+    /// comment.
+    ///
+    /// Very interesting documentation, definitely.
     pub const VAR_F: B = B(5);
 }
 impl ::std::ops::BitOr<B> for B {
diff --git a/bindgen-tests/tests/expectations/tests/enum-doc-mod.rs b/bindgen-tests/tests/expectations/tests/enum-doc-mod.rs
index 2b18b35df0..5f6227a768 100644
--- a/bindgen-tests/tests/expectations/tests/enum-doc-mod.rs
+++ b/bindgen-tests/tests/expectations/tests/enum-doc-mod.rs
@@ -12,9 +12,9 @@ pub mod B {
     pub const VAR_D: Type = 3;
     ///< Document field with following exclamation
     pub const VAR_E: Type = 4;
-    /** Document field with preceding star, with a loong long multiline
- comment.
-
- Very interesting documentation, definitely.*/
+    /// Document field with preceding star, with a loong long multiline
+    /// comment.
+    ///
+    /// Very interesting documentation, definitely.
     pub const VAR_F: Type = 5;
 }
diff --git a/bindgen-tests/tests/expectations/tests/enum-doc-rusty.rs b/bindgen-tests/tests/expectations/tests/enum-doc-rusty.rs
index 3eec0759c5..86a0560917 100644
--- a/bindgen-tests/tests/expectations/tests/enum-doc-rusty.rs
+++ b/bindgen-tests/tests/expectations/tests/enum-doc-rusty.rs
@@ -13,9 +13,9 @@ pub enum B {
     VAR_D = 3,
     ///< Document field with following exclamation
     VAR_E = 4,
-    /** Document field with preceding star, with a loong long multiline
- comment.
-
- Very interesting documentation, definitely.*/
+    /// Document field with preceding star, with a loong long multiline
+    /// comment.
+    ///
+    /// Very interesting documentation, definitely.
     VAR_F = 5,
 }
diff --git a/bindgen-tests/tests/expectations/tests/enum-doc.rs b/bindgen-tests/tests/expectations/tests/enum-doc.rs
index 98a7eed8f8..3853a25d1c 100644
--- a/bindgen-tests/tests/expectations/tests/enum-doc.rs
+++ b/bindgen-tests/tests/expectations/tests/enum-doc.rs
@@ -9,10 +9,10 @@ pub const B_VAR_C: B = 2;
 pub const B_VAR_D: B = 3;
 ///< Document field with following exclamation
 pub const B_VAR_E: B = 4;
-/** Document field with preceding star, with a loong long multiline
- comment.
-
- Very interesting documentation, definitely.*/
+/// Document field with preceding star, with a loong long multiline
+/// comment.
+///
+/// Very interesting documentation, definitely.
 pub const B_VAR_F: B = 5;
 /// Document enum
 pub type B = ::std::os::raw::c_uint;
diff --git a/bindgen-tests/tests/expectations/tests/enum-variant-replaces.rs b/bindgen-tests/tests/expectations/tests/enum-variant-replaces.rs
index a661ca833b..41e63bf217 100644
--- a/bindgen-tests/tests/expectations/tests/enum-variant-replaces.rs
+++ b/bindgen-tests/tests/expectations/tests/enum-variant-replaces.rs
@@ -1,11 +1,11 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
-/** <div rustbindgen replaces="PASS"></div>
-
- Should see PASS below.*/
+/// <div rustbindgen replaces="PASS"></div>
+///
+/// Should see PASS below.
 pub const OGRErr_PASS: OGRErr = 0;
-/** <div rustbindgen replaces="OGRERR_NONE"></div>
-
- Should see OGRERR_NONE instead of CUSTOM_OGRERR_NONE below.*/
+/// <div rustbindgen replaces="OGRERR_NONE"></div>
+///
+/// Should see OGRERR_NONE instead of CUSTOM_OGRERR_NONE below.
 pub const OGRErr_OGRERR_NONE: OGRErr = 1;
 /// <div rustbindgen replaces="OGRErr"></div>
 pub type OGRErr = ::std::os::raw::c_uint;
diff --git a/bindgen-tests/tests/expectations/tests/issue-1995.rs b/bindgen-tests/tests/expectations/tests/issue-1995.rs
index 0e36bdd9c9..78294ffa4e 100644
--- a/bindgen-tests/tests/expectations/tests/issue-1995.rs
+++ b/bindgen-tests/tests/expectations/tests/issue-1995.rs
@@ -1,11 +1,11 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
-/** This is a constant that has a docstring
-
- And expected to be found in generated bindings code too.*/
+/// This is a constant that has a docstring
+///
+/// And expected to be found in generated bindings code too.
 pub const FOO: ::std::os::raw::c_int = 1;
-/** This is a constant that has a docstring
-
- And expected to be found in generated bindings code too.*/
+/// This is a constant that has a docstring
+///
+/// And expected to be found in generated bindings code too.
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct Bar {
diff --git a/bindgen-tests/tests/expectations/tests/issue-537-repr-packed-n.rs b/bindgen-tests/tests/expectations/tests/issue-537-repr-packed-n.rs
index 0142673f3e..05802ccf59 100644
--- a/bindgen-tests/tests/expectations/tests/issue-537-repr-packed-n.rs
+++ b/bindgen-tests/tests/expectations/tests/issue-537-repr-packed-n.rs
@@ -1,7 +1,7 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
 #![cfg(feature = "nightly")]
-/** This should not be opaque; we can see the attributes and can pack the
- struct.*/
+/// This should not be opaque; we can see the attributes and can pack the
+/// struct.
 #[repr(C, packed)]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct AlignedToOne {
@@ -45,9 +45,9 @@ fn bindgen_test_layout_AlignedToTwo() {
         "Offset of field: AlignedToTwo::i",
     );
 }
-/** This should not be opaque because although `libclang` doesn't give us the
- `#pragma pack(1)`, we can detect that alignment is 1 and add
- `#[repr(packed)]` to the struct ourselves.*/
+/// This should not be opaque because although `libclang` doesn't give us the
+/// `#pragma pack(1)`, we can detect that alignment is 1 and add
+/// `#[repr(packed)]` to the struct ourselves.
 #[repr(C, packed)]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct PackedToOne {
diff --git a/bindgen-tests/tests/expectations/tests/issue-537.rs b/bindgen-tests/tests/expectations/tests/issue-537.rs
index d630b9ea4c..0e499c3661 100644
--- a/bindgen-tests/tests/expectations/tests/issue-537.rs
+++ b/bindgen-tests/tests/expectations/tests/issue-537.rs
@@ -1,6 +1,6 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
-/** This should not be opaque; we can see the attributes and can pack the
- struct.*/
+/// This should not be opaque; we can see the attributes and can pack the
+/// struct.
 #[repr(C, packed)]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct AlignedToOne {
@@ -14,8 +14,8 @@ const _: () = {
         "Offset of field: AlignedToOne::i",
     ][::std::mem::offset_of!(AlignedToOne, i) - 0usize];
 };
-/** This should be opaque because although we can see the attributes, Rust before
- 1.33 doesn't have `#[repr(packed(N))]`.*/
+/// This should be opaque because although we can see the attributes, Rust before
+/// 1.33 doesn't have `#[repr(packed(N))]`.
 #[repr(C, packed(2))]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct AlignedToTwo {
@@ -29,9 +29,9 @@ const _: () = {
         "Offset of field: AlignedToTwo::i",
     ][::std::mem::offset_of!(AlignedToTwo, i) - 0usize];
 };
-/** This should not be opaque because although `libclang` doesn't give us the
- `#pragma pack(1)`, we can detect that alignment is 1 and add
- `#[repr(packed)]` to the struct ourselves.*/
+/// This should not be opaque because although `libclang` doesn't give us the
+/// `#pragma pack(1)`, we can detect that alignment is 1 and add
+/// `#[repr(packed)]` to the struct ourselves.
 #[repr(C, packed)]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct PackedToOne {
@@ -45,9 +45,9 @@ const _: () = {
     ["Offset of field: PackedToOne::x"][::std::mem::offset_of!(PackedToOne, x) - 0usize];
     ["Offset of field: PackedToOne::y"][::std::mem::offset_of!(PackedToOne, y) - 4usize];
 };
-/** In this case, even if we can detect the weird alignment triggered by
- `#pragma pack(2)`, we can't do anything about it because Rust before 1.33
- doesn't have `#[repr(packed(N))]`. Therefore, we must make it opaque.*/
+/// In this case, even if we can detect the weird alignment triggered by
+/// `#pragma pack(2)`, we can't do anything about it because Rust before 1.33
+/// doesn't have `#[repr(packed(N))]`. Therefore, we must make it opaque.
 #[repr(C, packed(2))]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct PackedToTwo {
diff --git a/bindgen-tests/tests/expectations/tests/issue-648-derive-debug-with-padding.rs b/bindgen-tests/tests/expectations/tests/issue-648-derive-debug-with-padding.rs
index 08e47bc2c6..b92871e35d 100644
--- a/bindgen-tests/tests/expectations/tests/issue-648-derive-debug-with-padding.rs
+++ b/bindgen-tests/tests/expectations/tests/issue-648-derive-debug-with-padding.rs
@@ -1,6 +1,6 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
-/** We emit a `[u8; 63usize]` padding field for this struct, which cannot derive
- Debug/Hash because 63 is over the hard coded limit.*/
+/// We emit a `[u8; 63usize]` padding field for this struct, which cannot derive
+/// Debug/Hash because 63 is over the hard coded limit.
 #[repr(C)]
 #[repr(align(64))]
 #[derive(Copy, Clone)]
@@ -33,10 +33,10 @@ impl ::std::cmp::PartialEq for NoDebug {
         self.c == other.c
     }
 }
-/** This should derive Debug/Hash/PartialEq/Eq because the padding size is less than the max derive
- Debug/Hash/PartialEq/Eq impl for arrays. However, we conservatively don't derive Debug/Hash because
- we determine Debug derive-ability before we compute padding, which happens at
- codegen.*/
+/// This should derive Debug/Hash/PartialEq/Eq because the padding size is less than the max derive
+/// Debug/Hash/PartialEq/Eq impl for arrays. However, we conservatively don't derive Debug/Hash because
+/// we determine Debug derive-ability before we compute padding, which happens at
+/// codegen.
 #[repr(C)]
 #[repr(align(64))]
 #[derive(Copy, Clone)]
diff --git a/bindgen-tests/tests/expectations/tests/issue-848-replacement-system-include.rs b/bindgen-tests/tests/expectations/tests/issue-848-replacement-system-include.rs
index 6beeae69d8..518b80eda2 100644
--- a/bindgen-tests/tests/expectations/tests/issue-848-replacement-system-include.rs
+++ b/bindgen-tests/tests/expectations/tests/issue-848-replacement-system-include.rs
@@ -1,10 +1,10 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
-/** This is intended to replace another type, but won't if we treat this include
- as a system include, because clang doesn't parse comments there.
-
- See #848.
-
- <div rustbindgen replaces="nsTArray"></div>*/
+/// This is intended to replace another type, but won't if we treat this include
+/// as a system include, because clang doesn't parse comments there.
+///
+/// See #848.
+///
+/// <div rustbindgen replaces="nsTArray"></div>
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
 pub struct nsTArray<T> {
diff --git a/bindgen-tests/tests/expectations/tests/layout_arp.rs b/bindgen-tests/tests/expectations/tests/layout_arp.rs
index c94dc2ce24..50b62713ff 100644
--- a/bindgen-tests/tests/expectations/tests/layout_arp.rs
+++ b/bindgen-tests/tests/expectations/tests/layout_arp.rs
@@ -7,15 +7,15 @@ pub const ARP_OP_REVREQUEST: u32 = 3;
 pub const ARP_OP_REVREPLY: u32 = 4;
 pub const ARP_OP_INVREQUEST: u32 = 8;
 pub const ARP_OP_INVREPLY: u32 = 9;
-/** Ethernet address:
- A universally administered address is uniquely assigned to a device by its
- manufacturer. The first three octets (in transmission order) contain the
- Organizationally Unique Identifier (OUI). The following three (MAC-48 and
- EUI-48) octets are assigned by that organization with the only constraint
- of uniqueness.
- A locally administered address is assigned to a device by a network
- administrator and does not contain OUIs.
- See http://standards.ieee.org/regauth/groupmac/tutorial.html*/
+/// Ethernet address:
+/// A universally administered address is uniquely assigned to a device by its
+/// manufacturer. The first three octets (in transmission order) contain the
+/// Organizationally Unique Identifier (OUI). The following three (MAC-48 and
+/// EUI-48) octets are assigned by that organization with the only constraint
+/// of uniqueness.
+/// A locally administered address is assigned to a device by a network
+/// administrator and does not contain OUIs.
+/// See http://standards.ieee.org/regauth/groupmac/tutorial.html
 #[repr(C, packed)]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct ether_addr {
diff --git a/bindgen-tests/tests/expectations/tests/layout_array.rs b/bindgen-tests/tests/expectations/tests/layout_array.rs
index b910159beb..e3972803ce 100644
--- a/bindgen-tests/tests/expectations/tests/layout_array.rs
+++ b/bindgen-tests/tests/expectations/tests/layout_array.rs
@@ -8,14 +8,14 @@ pub const RTE_HEAP_NUM_FREELISTS: u32 = 13;
 pub struct rte_mempool {
     _unused: [u8; 0],
 }
-/** Prototype for implementation specific data provisioning function.
-
- The function should provide the implementation specific memory for
- for use by the other mempool ops functions in a given mempool ops struct.
- E.g. the default ops provides an instance of the rte_ring for this purpose.
- it will most likely point to a different type of data structure, and
- will be transparent to the application programmer.
- This function should set mp->pool_data.*/
+/// Prototype for implementation specific data provisioning function.
+///
+/// The function should provide the implementation specific memory for
+/// for use by the other mempool ops functions in a given mempool ops struct.
+/// E.g. the default ops provides an instance of the rte_ring for this purpose.
+/// it will most likely point to a different type of data structure, and
+/// will be transparent to the application programmer.
+/// This function should set mp->pool_data.
 pub type rte_mempool_alloc_t = ::std::option::Option<
     unsafe extern "C" fn(mp: *mut rte_mempool) -> ::std::os::raw::c_int,
 >;
@@ -149,13 +149,13 @@ fn bindgen_test_layout_rte_spinlock_t() {
         "Offset of field: rte_spinlock_t::locked",
     );
 }
-/** Structure storing the table of registered ops structs, each of which contain
- the function pointers for the mempool ops functions.
- Each process has its own storage for this ops struct array so that
- the mempools can be shared across primary and secondary processes.
- The indices used to access the array are valid across processes, whereas
- any function pointers stored directly in the mempool struct would not be.
- This results in us simply having "ops_index" in the mempool struct.*/
+/// Structure storing the table of registered ops structs, each of which contain
+/// the function pointers for the mempool ops functions.
+/// Each process has its own storage for this ops struct array so that
+/// the mempools can be shared across primary and secondary processes.
+/// The indices used to access the array are valid across processes, whereas
+/// any function pointers stored directly in the mempool struct would not be.
+/// This results in us simply having "ops_index" in the mempool struct.
 #[repr(C)]
 #[repr(align(64))]
 #[derive(Copy, Clone)]
diff --git a/bindgen-tests/tests/expectations/tests/layout_array_too_long.rs b/bindgen-tests/tests/expectations/tests/layout_array_too_long.rs
index d6ce2883d7..064c072af8 100644
--- a/bindgen-tests/tests/expectations/tests/layout_array_too_long.rs
+++ b/bindgen-tests/tests/expectations/tests/layout_array_too_long.rs
@@ -95,8 +95,8 @@ fn bindgen_test_layout_ip_frag_key() {
         "Offset of field: ip_frag_key::key_len",
     );
 }
-/** @internal Fragmented packet to reassemble.
- First two entries in the frags[] array are for the last and first fragments.*/
+/// @internal Fragmented packet to reassemble.
+/// First two entries in the frags[] array are for the last and first fragments.
 #[repr(C)]
 #[repr(align(64))]
 #[derive(Copy, Clone)]
diff --git a/bindgen-tests/tests/expectations/tests/layout_cmdline_token.rs b/bindgen-tests/tests/expectations/tests/layout_cmdline_token.rs
index fb7b3bf584..3102924a54 100644
--- a/bindgen-tests/tests/expectations/tests/layout_cmdline_token.rs
+++ b/bindgen-tests/tests/expectations/tests/layout_cmdline_token.rs
@@ -1,6 +1,6 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
-/** Stores a pointer to the ops struct, and the offset: the place to
- write the parsed result in the destination structure.*/
+/// Stores a pointer to the ops struct, and the offset: the place to
+/// write the parsed result in the destination structure.
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
 pub struct cmdline_token_hdr {
@@ -29,26 +29,26 @@ impl Default for cmdline_token_hdr {
         }
     }
 }
-/** Stores a pointer to the ops struct, and the offset: the place to
- write the parsed result in the destination structure.*/
+/// Stores a pointer to the ops struct, and the offset: the place to
+/// write the parsed result in the destination structure.
 pub type cmdline_parse_token_hdr_t = cmdline_token_hdr;
-/** A token is defined by this structure.
-
- parse() takes the token as first argument, then the source buffer
- starting at the token we want to parse. The 3rd arg is a pointer
- where we store the parsed data (as binary). It returns the number of
- parsed chars on success and a negative value on error.
-
- complete_get_nb() returns the number of possible values for this
- token if completion is possible. If it is NULL or if it returns 0,
- no completion is possible.
-
- complete_get_elt() copy in dstbuf (the size is specified in the
- parameter) the i-th possible completion for this token.  returns 0
- on success or and a negative value on error.
-
- get_help() fills the dstbuf with the help for the token. It returns
- -1 on error and 0 on success.*/
+/// A token is defined by this structure.
+///
+/// parse() takes the token as first argument, then the source buffer
+/// starting at the token we want to parse. The 3rd arg is a pointer
+/// where we store the parsed data (as binary). It returns the number of
+/// parsed chars on success and a negative value on error.
+///
+/// complete_get_nb() returns the number of possible values for this
+/// token if completion is possible. If it is NULL or if it returns 0,
+/// no completion is possible.
+///
+/// complete_get_elt() copy in dstbuf (the size is specified in the
+/// parameter) the i-th possible completion for this token.  returns 0
+/// on success or and a negative value on error.
+///
+/// get_help() fills the dstbuf with the help for the token. It returns
+/// -1 on error and 0 on success.
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct cmdline_token_ops {
diff --git a/bindgen-tests/tests/expectations/tests/layout_eth_conf.rs b/bindgen-tests/tests/expectations/tests/layout_eth_conf.rs
index 4a62ddbea3..63d7e006ac 100644
--- a/bindgen-tests/tests/expectations/tests/layout_eth_conf.rs
+++ b/bindgen-tests/tests/expectations/tests/layout_eth_conf.rs
@@ -120,8 +120,8 @@ pub const RTE_ETH_FLOW_GENEVE: u32 = 20;
 pub const RTE_ETH_FLOW_NVGRE: u32 = 21;
 pub const RTE_ETH_FLOW_MAX: u32 = 22;
 #[repr(u32)]
-/**  A set of values to identify what method is to be used to route
-  packets to multiple queues.*/
+///  A set of values to identify what method is to be used to route
+///  packets to multiple queues.
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 pub enum rte_eth_rx_mq_mode {
     /// None of DCB,RSS or VMDQ mode
@@ -405,8 +405,8 @@ impl rte_eth_rxmode {
     }
 }
 #[repr(u32)]
-/** A set of values to identify what method is to be used to transmit
- packets using multi-TCs.*/
+/// A set of values to identify what method is to be used to transmit
+/// packets using multi-TCs.
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 pub enum rte_eth_tx_mq_mode {
     ///< It is in neither DCB nor VT mode.
@@ -540,21 +540,21 @@ impl rte_eth_txmode {
         __bindgen_bitfield_unit
     }
 }
-/** A structure used to configure the Receive Side Scaling (RSS) feature
- of an Ethernet port.
- If not NULL, the *rss_key* pointer of the *rss_conf* structure points
- to an array holding the RSS key to use for hashing specific header
- fields of received packets. The length of this array should be indicated
- by *rss_key_len* below. Otherwise, a default random hash key is used by
- the device driver.
-
- The *rss_key_len* field of the *rss_conf* structure indicates the length
- in bytes of the array pointed by *rss_key*. To be compatible, this length
- will be checked in i40e only. Others assume 40 bytes to be used as before.
-
- The *rss_hf* field of the *rss_conf* structure indicates the different
- types of IPv4/IPv6 packets to which the RSS hashing must be applied.
- Supplying an *rss_hf* equal to zero disables the RSS feature.*/
+/// A structure used to configure the Receive Side Scaling (RSS) feature
+/// of an Ethernet port.
+/// If not NULL, the *rss_key* pointer of the *rss_conf* structure points
+/// to an array holding the RSS key to use for hashing specific header
+/// fields of received packets. The length of this array should be indicated
+/// by *rss_key_len* below. Otherwise, a default random hash key is used by
+/// the device driver.
+///
+/// The *rss_key_len* field of the *rss_conf* structure indicates the length
+/// in bytes of the array pointed by *rss_key*. To be compatible, this length
+/// will be checked in i40e only. Others assume 40 bytes to be used as before.
+///
+/// The *rss_hf* field of the *rss_conf* structure indicates the different
+/// types of IPv4/IPv6 packets to which the RSS hashing must be applied.
+/// Supplying an *rss_hf* equal to zero disables the RSS feature.
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 pub struct rte_eth_rss_conf {
@@ -605,8 +605,8 @@ impl Default for rte_eth_rss_conf {
     }
 }
 #[repr(u32)]
-/** This enum indicates the possible number of traffic classes
- in DCB configratioins*/
+/// This enum indicates the possible number of traffic classes
+/// in DCB configratioins
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 pub enum rte_eth_nb_tcs {
     ///< 4 TCs with DCB.
@@ -615,8 +615,8 @@ pub enum rte_eth_nb_tcs {
     ETH_8_TCS = 8,
 }
 #[repr(u32)]
-/** This enum indicates the possible number of queue pools
- in VMDQ configurations.*/
+/// This enum indicates the possible number of queue pools
+/// in VMDQ configurations.
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 pub enum rte_eth_nb_pools {
     ///< 8 VMDq pools.
@@ -628,15 +628,15 @@ pub enum rte_eth_nb_pools {
     ///< 64 VMDq pools.
     ETH_64_POOLS = 64,
 }
-/** A structure used to configure the VMDQ+DCB feature
- of an Ethernet port.
-
- Using this feature, packets are routed to a pool of queues, based
- on the vlan ID in the vlan tag, and then to a specific queue within
- that pool, using the user priority vlan tag field.
-
- A default pool may be used, if desired, to route all traffic which
- does not match the vlan filter rules.*/
+/// A structure used to configure the VMDQ+DCB feature
+/// of an Ethernet port.
+///
+/// Using this feature, packets are routed to a pool of queues, based
+/// on the vlan ID in the vlan tag, and then to a specific queue within
+/// that pool, using the user priority vlan tag field.
+///
+/// A default pool may be used, if desired, to route all traffic which
+/// does not match the vlan filter rules.
 #[repr(C)]
 #[derive(Copy, Clone)]
 pub struct rte_eth_vmdq_dcb_conf {
@@ -1030,8 +1030,8 @@ pub enum rte_fdir_mode {
     RTE_FDIR_MODE_PERFECT_TUNNEL = 4,
 }
 #[repr(u32)]
-/**  Memory space that can be configured to store Flow Director filters
-  in the board memory.*/
+///  Memory space that can be configured to store Flow Director filters
+///  in the board memory.
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 pub enum rte_fdir_pballoc_type {
     ///< 64k.
@@ -1162,8 +1162,8 @@ fn bindgen_test_layout_rte_eth_ipv6_flow() {
         "Offset of field: rte_eth_ipv6_flow::hop_limits",
     );
 }
-/**  A structure used to configure FDIR masks that are used by the device
-  to match the various fields of RX packet headers.*/
+///  A structure used to configure FDIR masks that are used by the device
+///  to match the various fields of RX packet headers.
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone, Hash, PartialEq, Eq)]
 pub struct rte_eth_fdir_masks {
@@ -1177,13 +1177,13 @@ pub struct rte_eth_fdir_masks {
     pub src_port_mask: u16,
     /// Bit mask for L4 destination port in big endian.
     pub dst_port_mask: u16,
-    /** 6 bit mask for proper 6 bytes of Mac address, bit 0 matches the
-first byte on the wire*/
+    /// 6 bit mask for proper 6 bytes of Mac address, bit 0 matches the
+    ///first byte on the wire
     pub mac_addr_byte_mask: u8,
     /// Bit mask for tunnel ID in big endian.
     pub tunnel_id_mask: u32,
-    /**< 1 - Match tunnel type,
-0 - Ignore tunnel type.*/
+    ///< 1 - Match tunnel type,
+    ///0 - Ignore tunnel type.
     pub tunnel_type_mask: u8,
 }
 #[test]
@@ -1254,8 +1254,8 @@ pub enum rte_eth_payload_type {
     RTE_ETH_L4_PAYLOAD = 4,
     RTE_ETH_PAYLOAD_MAX = 8,
 }
-/** A structure used to select bytes extracted from the protocol layers to
- flexible payload for filter*/
+/// A structure used to select bytes extracted from the protocol layers to
+/// flexible payload for filter
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 pub struct rte_eth_flex_payload_cfg {
@@ -1297,8 +1297,8 @@ impl Default for rte_eth_flex_payload_cfg {
         }
     }
 }
-/** A structure used to define FDIR masks for flexible payload
- for each flow type*/
+/// A structure used to define FDIR masks for flexible payload
+/// for each flow type
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone, Hash, PartialEq, Eq)]
 pub struct rte_eth_fdir_flex_mask {
@@ -1330,8 +1330,8 @@ fn bindgen_test_layout_rte_eth_fdir_flex_mask() {
         "Offset of field: rte_eth_fdir_flex_mask::mask",
     );
 }
-/** A structure used to define all flexible payload related setting
- include flex payload and flex mask*/
+/// A structure used to define all flexible payload related setting
+/// include flex payload and flex mask
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 pub struct rte_eth_fdir_flex_conf {
@@ -1386,10 +1386,10 @@ impl Default for rte_eth_fdir_flex_conf {
         }
     }
 }
-/** A structure used to configure the Flow Director (FDIR) feature
- of an Ethernet port.
-
- If mode is RTE_FDIR_DISABLE, the pballoc value is ignored.*/
+/// A structure used to configure the Flow Director (FDIR) feature
+/// of an Ethernet port.
+///
+/// If mode is RTE_FDIR_DISABLE, the pballoc value is ignored.
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 pub struct rte_fdir_conf {
@@ -1488,36 +1488,36 @@ fn bindgen_test_layout_rte_intr_conf() {
         "Offset of field: rte_intr_conf::rxq",
     );
 }
-/** A structure used to configure an Ethernet port.
- Depending upon the RX multi-queue mode, extra advanced
- configuration settings may be needed.*/
+/// A structure used to configure an Ethernet port.
+/// Depending upon the RX multi-queue mode, extra advanced
+/// configuration settings may be needed.
 #[repr(C)]
 #[derive(Copy, Clone)]
 pub struct rte_eth_conf {
-    /**< bitmap of ETH_LINK_SPEED_XXX of speeds to be
-used. ETH_LINK_SPEED_FIXED disables link
-autonegotiation, and a unique speed shall be
-set. Otherwise, the bitmap defines the set of
-speeds to be advertised. If the special value
-ETH_LINK_SPEED_AUTONEG (0) is used, all speeds
-supported are advertised.*/
+    ///< bitmap of ETH_LINK_SPEED_XXX of speeds to be
+    ///used. ETH_LINK_SPEED_FIXED disables link
+    ///autonegotiation, and a unique speed shall be
+    ///set. Otherwise, the bitmap defines the set of
+    ///speeds to be advertised. If the special value
+    ///ETH_LINK_SPEED_AUTONEG (0) is used, all speeds
+    ///supported are advertised.
     pub link_speeds: u32,
     ///< Port RX configuration.
     pub rxmode: rte_eth_rxmode,
     ///< Port TX configuration.
     pub txmode: rte_eth_txmode,
-    /**< Loopback operation mode. By default the value
-is 0, meaning the loopback mode is disabled.
-Read the datasheet of given ethernet controller
-for details. The possible values of this field
-are defined in implementation of each driver.*/
+    ///< Loopback operation mode. By default the value
+    ///is 0, meaning the loopback mode is disabled.
+    ///Read the datasheet of given ethernet controller
+    ///for details. The possible values of this field
+    ///are defined in implementation of each driver.
     pub lpbk_mode: u32,
     ///< Port RX filtering configuration (union).
     pub rx_adv_conf: rte_eth_conf__bindgen_ty_1,
     ///< Port TX DCB configuration (union).
     pub tx_adv_conf: rte_eth_conf__bindgen_ty_2,
-    /** Currently,Priority Flow Control(PFC) are supported,if DCB with PFC
-is needed,and the variable must be set ETH_DCB_PFC_SUPPORT.*/
+    /// Currently,Priority Flow Control(PFC) are supported,if DCB with PFC
+    ///is needed,and the variable must be set ETH_DCB_PFC_SUPPORT.
     pub dcb_capability_en: u32,
     ///< FDIR configuration.
     pub fdir_conf: rte_fdir_conf,
diff --git a/bindgen-tests/tests/expectations/tests/layout_large_align_field.rs b/bindgen-tests/tests/expectations/tests/layout_large_align_field.rs
index b72c221dca..f17fa1d6a2 100644
--- a/bindgen-tests/tests/expectations/tests/layout_large_align_field.rs
+++ b/bindgen-tests/tests/expectations/tests/layout_large_align_field.rs
@@ -125,8 +125,8 @@ fn bindgen_test_layout_ip_frag_key() {
         "Offset of field: ip_frag_key::key_len",
     );
 }
-/** @internal Fragmented packet to reassemble.
- First two entries in the frags[] array are for the last and first fragments.*/
+/// @internal Fragmented packet to reassemble.
+/// First two entries in the frags[] array are for the last and first fragments.
 #[repr(C)]
 #[repr(align(64))]
 #[derive(Copy, Clone)]
diff --git a/bindgen-tests/tests/expectations/tests/layout_mbuf.rs b/bindgen-tests/tests/expectations/tests/layout_mbuf.rs
index 47ea51d2c2..ff282ba30c 100644
--- a/bindgen-tests/tests/expectations/tests/layout_mbuf.rs
+++ b/bindgen-tests/tests/expectations/tests/layout_mbuf.rs
@@ -203,18 +203,18 @@ pub struct rte_mbuf {
     ///< Next segment of scattered packet.
     pub next: *mut rte_mbuf,
     pub __bindgen_anon_4: rte_mbuf__bindgen_ty_5,
-    /** Size of the application private data. In case of an indirect
- mbuf, it stores the direct mbuf private data size.*/
+    /// Size of the application private data. In case of an indirect
+    /// mbuf, it stores the direct mbuf private data size.
     pub priv_size: u16,
     /// Timesync flags for use with IEEE1588.
     pub timesync: u16,
 }
-/** 16-bit Reference counter.
- It should only be accessed using the following functions:
- rte_mbuf_refcnt_update(), rte_mbuf_refcnt_read(), and
- rte_mbuf_refcnt_set(). The functionality of these functions (atomic,
- or non-atomic) is controlled by the CONFIG_RTE_MBUF_REFCNT_ATOMIC
- config option.*/
+/// 16-bit Reference counter.
+/// It should only be accessed using the following functions:
+/// rte_mbuf_refcnt_update(), rte_mbuf_refcnt_read(), and
+/// rte_mbuf_refcnt_set(). The functionality of these functions (atomic,
+/// or non-atomic) is controlled by the CONFIG_RTE_MBUF_REFCNT_ATOMIC
+/// config option.
 #[repr(C)]
 #[derive(Copy, Clone)]
 pub union rte_mbuf__bindgen_ty_1 {
diff --git a/bindgen-tests/tests/expectations/tests/no-derive-debug.rs b/bindgen-tests/tests/expectations/tests/no-derive-debug.rs
index 5e525068fd..147a6abe27 100644
--- a/bindgen-tests/tests/expectations/tests/no-derive-debug.rs
+++ b/bindgen-tests/tests/expectations/tests/no-derive-debug.rs
@@ -4,9 +4,9 @@
 pub struct foo {
     bar: ::std::os::raw::c_int,
 }
-/** bar should compile. It will normally derive debug, but our blocklist of foo
- and replacement for another type that doesn't implement it would prevent it
- from building if --no-derive-debug didn't work.*/
+/// bar should compile. It will normally derive debug, but our blocklist of foo
+/// and replacement for another type that doesn't implement it would prevent it
+/// from building if --no-derive-debug didn't work.
 #[repr(C)]
 pub struct bar {
     pub foo: foo,
diff --git a/bindgen-tests/tests/expectations/tests/no-derive-default.rs b/bindgen-tests/tests/expectations/tests/no-derive-default.rs
index a1d86a6502..f2051f6b75 100644
--- a/bindgen-tests/tests/expectations/tests/no-derive-default.rs
+++ b/bindgen-tests/tests/expectations/tests/no-derive-default.rs
@@ -4,9 +4,9 @@
 pub struct foo {
     bar: ::std::os::raw::c_int,
 }
-/** bar should compile. It will normally derive default, but our blocklist of foo
- and replacement for another type that doesn't implement it would prevent it
- from building if --no-derive-default didn't work.*/
+/// bar should compile. It will normally derive default, but our blocklist of foo
+/// and replacement for another type that doesn't implement it would prevent it
+/// from building if --no-derive-default didn't work.
 #[repr(C)]
 pub struct bar {
     pub foo: foo,
diff --git a/bindgen-tests/tests/expectations/tests/opaque-template-inst-member-2.rs b/bindgen-tests/tests/expectations/tests/opaque-template-inst-member-2.rs
index 14718a9312..9661fcaa5b 100644
--- a/bindgen-tests/tests/expectations/tests/opaque-template-inst-member-2.rs
+++ b/bindgen-tests/tests/expectations/tests/opaque-template-inst-member-2.rs
@@ -1,6 +1,6 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
-/** This is like `opaque-template-inst-member.hpp` except exercising the cases
- where we are OK to derive Debug/Hash/PartialEq.*/
+/// This is like `opaque-template-inst-member.hpp` except exercising the cases
+/// where we are OK to derive Debug/Hash/PartialEq.
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone, Hash, PartialEq, Eq)]
 pub struct OpaqueTemplate {
diff --git a/bindgen-tests/tests/expectations/tests/opaque-template-inst-member.rs b/bindgen-tests/tests/expectations/tests/opaque-template-inst-member.rs
index 4b070fa697..92bc4d324e 100644
--- a/bindgen-tests/tests/expectations/tests/opaque-template-inst-member.rs
+++ b/bindgen-tests/tests/expectations/tests/opaque-template-inst-member.rs
@@ -4,8 +4,8 @@
 pub struct OpaqueTemplate {
     pub _address: u8,
 }
-/** This should not end up deriving Debug/Hash because its `mBlah` field cannot derive
- Debug/Hash because the instantiation's definition cannot derive Debug/Hash.*/
+/// This should not end up deriving Debug/Hash because its `mBlah` field cannot derive
+/// Debug/Hash because the instantiation's definition cannot derive Debug/Hash.
 #[repr(C)]
 pub struct ContainsOpaqueTemplate {
     pub mBlah: [u32; 101usize],
@@ -50,8 +50,8 @@ impl ::std::cmp::PartialEq for ContainsOpaqueTemplate {
         &self.mBlah[..] == &other.mBlah[..] && self.mBaz == other.mBaz
     }
 }
-/** This should not end up deriving Debug/Hash either, for similar reasons, although
- we're exercising base member edges now.*/
+/// This should not end up deriving Debug/Hash either, for similar reasons, although
+/// we're exercising base member edges now.
 #[repr(C)]
 pub struct InheritsOpaqueTemplate {
     pub _base: [u8; 401usize],
diff --git a/bindgen-tests/tests/expectations/tests/replace_template_alias.rs b/bindgen-tests/tests/expectations/tests/replace_template_alias.rs
index 2efa164ddf..4dff0bacc5 100644
--- a/bindgen-tests/tests/expectations/tests/replace_template_alias.rs
+++ b/bindgen-tests/tests/expectations/tests/replace_template_alias.rs
@@ -1,7 +1,7 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
-/** But the replacement type does use T!
-
- <div rustbindgen replaces="JS::detail::MaybeWrapped" />*/
+/// But the replacement type does use T!
+///
+/// <div rustbindgen replaces="JS::detail::MaybeWrapped" />
 pub type JS_detail_MaybeWrapped<T> = T;
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
diff --git a/bindgen-tests/tests/expectations/tests/template.rs b/bindgen-tests/tests/expectations/tests/template.rs
index 94678cb49e..46c9503661 100644
--- a/bindgen-tests/tests/expectations/tests/template.rs
+++ b/bindgen-tests/tests/expectations/tests/template.rs
@@ -307,10 +307,10 @@ const _: () = {
 pub struct Templated {
     pub m_untemplated: Untemplated,
 }
-/** If the replacement doesn't happen at the parse level the container would be
- copy and the replacement wouldn't, so this wouldn't compile.
-
- <div rustbindgen replaces="ReplacedWithoutDestructor"></div>*/
+/// If the replacement doesn't happen at the parse level the container would be
+/// copy and the replacement wouldn't, so this wouldn't compile.
+///
+/// <div rustbindgen replaces="ReplacedWithoutDestructor"></div>
 #[repr(C)]
 #[derive(Debug, Hash, PartialEq, Eq)]
 pub struct ReplacedWithoutDestructor<T> {
@@ -356,10 +356,10 @@ impl<U> Default for ShouldNotBeCopiableAsWell<U> {
         }
     }
 }
-/** If the replacement doesn't happen at the parse level the container would be
- copy and the replacement wouldn't, so this wouldn't compile.
-
- <div rustbindgen replaces="ReplacedWithoutDestructorFwd"></div>*/
+/// If the replacement doesn't happen at the parse level the container would be
+/// copy and the replacement wouldn't, so this wouldn't compile.
+///
+/// <div rustbindgen replaces="ReplacedWithoutDestructorFwd"></div>
 #[repr(C)]
 #[derive(Debug, Hash, PartialEq, Eq)]
 pub struct ReplacedWithoutDestructorFwd<T> {
diff --git a/bindgen-tests/tests/expectations/tests/templatized-bitfield.rs b/bindgen-tests/tests/expectations/tests/templatized-bitfield.rs
index 1b3e712361..15cfe47a75 100644
--- a/bindgen-tests/tests/expectations/tests/templatized-bitfield.rs
+++ b/bindgen-tests/tests/expectations/tests/templatized-bitfield.rs
@@ -1,7 +1,7 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
-/** We don't get a layout for this bitfield, since we don't know what `T` will
- be, so we cannot allocate bitfield units. The best thing we can do is make
- the struct opaque.*/
+/// We don't get a layout for this bitfield, since we don't know what `T` will
+/// be, so we cannot allocate bitfield units. The best thing we can do is make
+/// the struct opaque.
 #[repr(C)]
 #[derive(Debug, Default, Copy, Clone)]
 pub struct TemplatizedBitfield {
diff --git a/bindgen-tests/tests/expectations/tests/zero-sized-array.rs b/bindgen-tests/tests/expectations/tests/zero-sized-array.rs
index 229a6ee4db..399c0bee06 100644
--- a/bindgen-tests/tests/expectations/tests/zero-sized-array.rs
+++ b/bindgen-tests/tests/expectations/tests/zero-sized-array.rs
@@ -61,8 +61,8 @@ const _: () = {
         "Offset of field: ContainsZeroSizedArray::zsa",
     ][::std::mem::offset_of!(ContainsZeroSizedArray, zsa) - 0usize];
 };
-/** Inheriting from ZeroSizedArray shouldn't cause an `_address` to be inserted
- either.*/
+/// Inheriting from ZeroSizedArray shouldn't cause an `_address` to be inserted
+/// either.
 #[repr(C)]
 #[derive(Debug, Default)]
 pub struct InheritsZeroSizedArray {
diff --git a/bindgen/codegen/helpers.rs b/bindgen/codegen/helpers.rs
index 7b09ed7cfb..fd44eee418 100644
--- a/bindgen/codegen/helpers.rs
+++ b/bindgen/codegen/helpers.rs
@@ -56,7 +56,9 @@ pub(crate) mod attributes {
         if comment.is_empty() {
             quote!()
         } else {
-            quote!(#[doc = #comment])
+            let doc_lines =
+                comment.lines().map(|line| quote! { #[doc = #line] });
+            quote!(#(#doc_lines)*)
         }
     }