Skip to content

Commit 3258c5a

Browse files
emilioemilio
committed
Make doc comments nice again.
1 parent b678c8a commit 3258c5a

File tree

72 files changed

+941
-580
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

72 files changed

+941
-580
lines changed

‎src/codegen/helpers.rs

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,14 @@ pub mod attributes {
3838
}
3939

4040
pub fn doc(comment: String) -> quote::Tokens {
41-
quote!(#[doc=#comment])
41+
// Doc comments are already preprocessed into nice `///` formats by the
42+
// time they get here. Just make sure that we have newlines around it so
43+
// that nothing else gets wrapped into the comment.
44+
let mut tokens = quote! {};
45+
tokens.append(Term::new("\n", Span::call_site()));
46+
tokens.append(Term::new(&comment, Span::call_site()));
47+
tokens.append(Term::new("\n", Span::call_site()));
48+
tokens
4249
}
4350

4451
pub fn link_name(name: &str) -> quote::Tokens {

‎src/ir/comment.rs

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ fn preprocess_single_lines(comment: &str, indent: usize) -> String {
5454
let indent = if is_first { "" } else { &*indent };
5555
is_first = false;
5656
let maybe_space = if l.is_empty() { "" } else { " " };
57-
format!("{}{}{}", indent, maybe_space, l)
57+
format!("{}///{}{}", indent, maybe_space, l)
5858
})
5959
.collect();
6060
lines.join("\n")
@@ -79,7 +79,7 @@ fn preprocess_multi_line(comment: &str, indent: usize) -> String {
7979
let indent = if is_first { "" } else { &*indent };
8080
is_first = false;
8181
let maybe_space = if line.is_empty() { "" } else { " " };
82-
format!("{}{}{}", indent, maybe_space, line)
82+
format!("{}///{}{}", indent, maybe_space, line)
8383
})
8484
.collect();
8585

@@ -105,20 +105,20 @@ mod test {
105105

106106
#[test]
107107
fn processes_single_lines_correctly() {
108-
assert_eq!(preprocess("/// hello", 0), " hello");
109-
assert_eq!(preprocess("// hello", 0), " hello");
108+
assert_eq!(preprocess("/// hello", 0), "/// hello");
109+
assert_eq!(preprocess("// hello", 0), "/// hello");
110110
}
111111

112112
#[test]
113113
fn processes_multi_lines_correctly() {
114114
assert_eq!(
115115
preprocess("/** hello \n * world \n * foo \n */", 0),
116-
" hello\n world\n foo"
116+
"/// hello\n/// world\n/// foo"
117117
);
118118

119119
assert_eq!(
120120
preprocess("/**\nhello\n*world\n*foo\n*/", 0),
121-
" hello\n world\n foo"
121+
"/// hello\n/// world\n/// foo"
122122
);
123123
}
124124
}

‎tests/expectations/tests/accessors.rs

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
/* automatically generated by rust-bindgen */
22

3+
34
#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
45

6+
57
#[repr(C)]
68
#[derive(Debug, Default, Copy, Clone)]
79
pub struct SomeAccessors {
810
pub mNoAccessor: ::std::os::raw::c_int,
9-
#[doc = " <div rustbindgen accessor></div>"]
11+
/// <div rustbindgen accessor></div>
1012
pub mBothAccessors: ::std::os::raw::c_int,
11-
#[doc = " <div rustbindgen accessor=\"unsafe\"></div>"]
13+
/// <div rustbindgen accessor="unsafe"></div>
1214
pub mUnsafeAccessors: ::std::os::raw::c_int,
13-
#[doc = " <div rustbindgen accessor=\"immutable\"></div>"]
15+
/// <div rustbindgen accessor="immutable"></div>
1416
pub mImmutableAccessor: ::std::os::raw::c_int,
1517
}
1618
#[test]
@@ -90,7 +92,7 @@ impl SomeAccessors {
9092
&self.mImmutableAccessor
9193
}
9294
}
93-
#[doc = " <div rustbindgen accessor></div>"]
95+
/// <div rustbindgen accessor></div>
9496
#[repr(C)]
9597
#[derive(Debug, Default, Copy, Clone)]
9698
pub struct AllAccessors {
@@ -148,7 +150,7 @@ impl AllAccessors {
148150
&mut self.mAlsoBothAccessors
149151
}
150152
}
151-
#[doc = " <div rustbindgen accessor=\"unsafe\"></div>"]
153+
/// <div rustbindgen accessor="unsafe"></div>
152154
#[repr(C)]
153155
#[derive(Debug, Default, Copy, Clone)]
154156
pub struct AllUnsafeAccessors {
@@ -210,16 +212,16 @@ impl AllUnsafeAccessors {
210212
&mut self.mAlsoBothAccessors
211213
}
212214
}
213-
#[doc = " <div rustbindgen accessor></div>"]
215+
/// <div rustbindgen accessor></div>
214216
#[repr(C)]
215217
#[derive(Debug, Default, Copy, Clone)]
216218
pub struct ContradictAccessors {
217219
pub mBothAccessors: ::std::os::raw::c_int,
218-
#[doc = " <div rustbindgen accessor=\"false\"></div>"]
220+
/// <div rustbindgen accessor="false"></div>
219221
pub mNoAccessors: ::std::os::raw::c_int,
220-
#[doc = " <div rustbindgen accessor=\"unsafe\"></div>"]
222+
/// <div rustbindgen accessor="unsafe"></div>
221223
pub mUnsafeAccessors: ::std::os::raw::c_int,
222-
#[doc = " <div rustbindgen accessor=\"immutable\"></div>"]
224+
/// <div rustbindgen accessor="immutable"></div>
223225
pub mImmutableAccessor: ::std::os::raw::c_int,
224226
}
225227
#[test]
@@ -305,7 +307,7 @@ impl ContradictAccessors {
305307
&self.mImmutableAccessor
306308
}
307309
}
308-
#[doc = " <div rustbindgen accessor replaces=\"Replaced\"></div>"]
310+
/// <div rustbindgen accessor replaces="Replaced"></div>
309311
#[repr(C)]
310312
#[derive(Debug, Default, Copy, Clone)]
311313
pub struct Replaced {
@@ -344,7 +346,7 @@ impl Replaced {
344346
&mut self.mAccessor
345347
}
346348
}
347-
#[doc = " <div rustbindgen accessor></div>"]
349+
/// <div rustbindgen accessor></div>
348350
#[repr(C)]
349351
#[derive(Debug, Default, Copy, Clone)]
350352
pub struct Wrapper {

‎tests/expectations/tests/annotation_hide.rs

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
/* automatically generated by rust-bindgen */
22

3+
34
#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
45

5-
#[doc = " <div rustbindgen opaque></div>"]
6+
7+
8+
/// <div rustbindgen opaque></div>
69
#[repr(C)]
710
#[derive(Debug, Default, Copy, Clone)]
811
pub struct D {

‎tests/expectations/tests/array-of-zero-sized-types.rs

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
/* automatically generated by rust-bindgen */
22

3+
34
#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
45

5-
#[doc = " This should get an `_address` byte."]
6+
7+
8+
/// This should get an `_address` byte.
69
#[repr(C)]
710
#[derive(Debug, Default, Copy, Clone)]
811
pub struct Empty {
@@ -21,7 +24,8 @@ fn bindgen_test_layout_Empty() {
2124
concat!("Alignment of ", stringify!(Empty))
2225
);
2326
}
24-
#[doc = " This should not get an `_address` byte, since each `Empty` gets one, meaning\n that this object is addressable."]
27+
/// This should not get an `_address` byte, since each `Empty` gets one, meaning
28+
/// that this object is addressable.
2529
#[repr(C)]
2630
#[derive(Debug, Default, Copy, Clone)]
2731
pub struct HasArrayOfEmpty {

‎tests/expectations/tests/blacklist-and-impl-debug.rs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
/* automatically generated by rust-bindgen */
22

3+
34
#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
45

56
pub struct BlacklistMe(u8);
67

7-
#[doc = " Because this type contains a blacklisted type, it should not derive Debug."]
8+
9+
/// Because this type contains a blacklisted type, it should not derive Debug.
810
#[repr(C)]
911
pub struct ShouldManuallyImplDebug {
1012
pub a: BlacklistMe,

‎tests/expectations/tests/class_use_as.rs

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
/* automatically generated by rust-bindgen */
22

3+
34
#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
45

5-
#[doc = " <div rustbindgen=\"true\" replaces=\"whatever\"></div>"]
6+
7+
8+
/// <div rustbindgen="true" replaces="whatever"></div>
69
#[repr(C)]
710
#[derive(Debug, Default, Copy, Clone, Hash, PartialEq, Eq)]
811
pub struct whatever {

‎tests/expectations/tests/comment-indent.rs

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,17 @@
66
pub mod root {
77
#[allow(unused_imports)]
88
use self::super::root;
9-
#[doc = " This is a multi-line doc comment.\n \n This class is really really interesting, look!"]
9+
/// This is a multi-line doc comment.
10+
///
11+
/// This class is really really interesting, look!
1012
#[repr(C)]
1113
#[derive(Debug, Default, Copy, Clone)]
1214
pub struct Foo {
1315
pub _address: u8,
1416
}
15-
#[doc = " This nested class is also a multi-line doc comment.\n \n This class is not so interesting, but worth a bit of docs too!"]
17+
/// This nested class is also a multi-line doc comment.
18+
///
19+
/// This class is not so interesting, but worth a bit of docs too!
1620
#[repr(C)]
1721
#[derive(Debug, Default, Copy, Clone)]
1822
pub struct Foo_Bar {
@@ -47,11 +51,18 @@ pub mod root {
4751
pub mod test {
4852
#[allow(unused_imports)]
4953
use self::super::super::root;
50-
#[doc = " I\'m in a namespace, and thus I may be on a rust module, most of the time.\n My documentation is pretty extensive, I guess."]
54+
/// I'm in a namespace, and thus I may be on a rust module, most of the time.
55+
/// My documentation is pretty extensive, I guess.
5156
#[repr(C)]
5257
#[derive(Debug, Default, Copy, Clone)]
5358
pub struct Baz {
54-
#[doc = " This member is plain awesome, just amazing.\n \n It also has super-extensive docs, with even a nice ascii-art diagram.\n \n +------+ +-------+\n | foo | ----> | bar |\n +------+ +-------+"]
59+
/// This member is plain awesome, just amazing.
60+
///
61+
/// It also has super-extensive docs, with even a nice ascii-art diagram.
62+
///
63+
/// +------+ +-------+
64+
/// | foo | ----> | bar |
65+
/// +------+ +-------+
5566
pub member: ::std::os::raw::c_int,
5667
}
5768
#[test]
@@ -77,7 +88,9 @@ pub mod root {
7788
)
7889
);
7990
}
80-
#[doc = " I\'m in an inline namespace, and as such I shouldn\'t get generated inside\n a rust module, except when the relevant option is specified. Also, this\n comment shouldn\'t be misaligned."]
91+
/// I'm in an inline namespace, and as such I shouldn't get generated inside
92+
/// a rust module, except when the relevant option is specified. Also, this
93+
/// comment shouldn't be misaligned.
8194
#[repr(C)]
8295
#[derive(Debug, Default, Copy, Clone)]
8396
pub struct InInlineNS {
@@ -96,7 +109,7 @@ pub mod root {
96109
concat!("Alignment of ", stringify!(InInlineNS))
97110
);
98111
}
99-
#[doc = ""]
112+
100113
#[repr(C)]
101114
#[derive(Debug, Default, Copy, Clone)]
102115
pub struct Bazz {

‎tests/expectations/tests/constify-enum.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,6 @@ pub enum nsCSSPropertyID {
1313
eCSSProperty_b = 1,
1414
eCSSPropertyAlias_aa = 2,
1515
eCSSPropertyAlias_bb = 3,
16-
#[doc = " < <div rustbindgen constant></div>"]
16+
/// < <div rustbindgen constant></div>
1717
eCSSProperty_COUNT_unexistingVariantValue = 4,
1818
}

‎tests/expectations/tests/contains-vs-inherits-zero-sized.rs

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
/* automatically generated by rust-bindgen */
22

3+
34
#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
45

5-
#[doc = " This should get an `_address` byte."]
6+
7+
8+
/// This should get an `_address` byte.
69
#[repr(C)]
710
#[derive(Debug, Default, Copy, Clone)]
811
pub struct Empty {
@@ -21,7 +24,8 @@ fn bindgen_test_layout_Empty() {
2124
concat!("Alignment of ", stringify!(Empty))
2225
);
2326
}
24-
#[doc = " This should not get an `_address` byte, so `sizeof(Inherits)` should be\n `1`."]
27+
/// This should not get an `_address` byte, so `sizeof(Inherits)` should be
28+
/// `1`.
2529
#[repr(C)]
2630
#[derive(Debug, Default, Copy, Clone)]
2731
pub struct Inherits {
@@ -50,7 +54,8 @@ fn bindgen_test_layout_Inherits() {
5054
)
5155
);
5256
}
53-
#[doc = " This should not get an `_address` byte, but contains `Empty` which *does* get\n one, so `sizeof(Contains)` should be `1 + 1`."]
57+
/// This should not get an `_address` byte, but contains `Empty` which *does* get
58+
/// one, so `sizeof(Contains)` should be `1 + 1`.
5459
#[repr(C)]
5560
#[derive(Debug, Default, Copy, Clone)]
5661
pub struct Contains {

‎tests/expectations/tests/convert-cpp-comment-to-rust.rs

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,19 @@
11
/* automatically generated by rust-bindgen */
22

3+
34
#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
45

6+
57
pub type mbedtls_mpi_uint = ::std::os::raw::c_uint;
6-
#[doc = " \\brief MPI structure"]
8+
/// \brief MPI structure
79
#[repr(C)]
810
#[derive(Debug, Copy, Clone)]
911
pub struct mbedtls_mpi {
10-
#[doc = " < integer sign"]
12+
/// < integer sign
1113
pub s: ::std::os::raw::c_int,
12-
#[doc = " < total # of limbs"]
14+
/// < total # of limbs
1315
pub n: ::std::os::raw::c_ulong,
14-
#[doc = " < pointer to limbs"]
16+
/// < pointer to limbs
1517
pub p: *mut mbedtls_mpi_uint,
1618
}
1719
#[test]

‎tests/expectations/tests/derive-bitfield-method-same-name.rs

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,10 @@ where
8181
}
8282
}
8383
}
84-
#[doc = " Because this struct have array larger than 32 items\n and --with-derive-partialeq --impl-partialeq --impl-debug is provided,\n this struct should manually implement `Debug` and `PartialEq`."]
84+
85+
/// Because this struct have array larger than 32 items
86+
/// and --with-derive-partialeq --impl-partialeq --impl-debug is provided,
87+
/// this struct should manually implement `Debug` and `PartialEq`.
8588
#[repr(C)]
8689
#[derive(Copy, Clone)]
8790
pub struct Foo {

‎tests/expectations/tests/derive-clone.rs

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
/* automatically generated by rust-bindgen */
22

3+
34
#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
45

5-
#[doc = " This struct should derive `Clone`."]
6+
7+
8+
/// This struct should derive `Clone`.
69
#[repr(C)]
710
#[derive(Copy, Clone)]
811
pub struct ShouldDeriveClone {

‎tests/expectations/tests/derive-clone_1_0.rs

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
/* automatically generated by rust-bindgen */
22

3+
34
#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
45

5-
#[doc = " Since builtin `Clone` impls were introduced in Rust 1.21 this struct\n should impl `Clone` \"manually\"."]
6+
7+
8+
/// Since builtin `Clone` impls were introduced in Rust 1.21 this struct
9+
/// should impl `Clone` "manually".
610
#[repr(C)]
711
#[derive(Copy)]
812
pub struct ShouldImplClone {

‎tests/expectations/tests/derive-default-and-blacklist.rs

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
/* automatically generated by rust-bindgen */
22

3+
34
#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
45

56
pub struct BlacklistMe(u8);
67

7-
#[doc = " Because this type contains a blacklisted type, it should not derive\n Default. Instead, we should emit a `mem::zeroed` implementation."]
8+
9+
/// Because this type contains a blacklisted type, it should not derive
10+
/// Default. Instead, we should emit a `mem::zeroed` implementation.
811
#[repr(C)]
912
pub struct ShouldNotDeriveDefault {
1013
pub a: BlacklistMe,

‎tests/expectations/tests/derive-hash-and-blacklist.rs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
/* automatically generated by rust-bindgen */
22

3+
34
#![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
45

56
pub struct BlacklistMe(u8);
67

7-
#[doc = " Because this type contains a blacklisted type, it should not derive Hash."]
8+
9+
/// Because this type contains a blacklisted type, it should not derive Hash.
810
#[repr(C)]
911
pub struct ShouldNotDeriveHash {
1012
pub a: BlacklistMe,

0 commit comments

Comments
 (0)