From b4b82a500cf588c4bd7d2fb198a1f03483dca1e1 Mon Sep 17 00:00:00 2001 From: Bruno Kirschner Date: Tue, 23 Jul 2019 11:57:36 +0200 Subject: [PATCH] Preserve empty lines in doc comments. This required two changes in parallel. As a first and obvious step it removes a check that skipped emptys lines during documentation loading, but it was also necessary to refactore the `get_comment_lines()` utility method as a second step. This second refactoring was necessary as each line in a doc comment is trimmed and transformed in its own doc attribute. The attribute of an empty line therefore contains an empty string as value. If we now call `lines()` on such an empty string we end up with an empty iterator as the method is internally configured to ignore trailing empty lines. --- src/bindgen/ir/documentation.rs | 2 +- src/bindgen/utilities.rs | 34 +++++++++++-------- tests/expectations/associated_in_body.c | 1 + .../expectations/associated_in_body.compat.c | 1 + tests/expectations/associated_in_body.cpp | 1 + tests/expectations/bitflags.c | 1 + tests/expectations/bitflags.compat.c | 1 + tests/expectations/bitflags.cpp | 1 + tests/expectations/both/associated_in_body.c | 1 + .../both/associated_in_body.compat.c | 1 + tests/expectations/both/bitflags.c | 1 + tests/expectations/both/bitflags.compat.c | 1 + tests/expectations/both/documentation.c | 17 ++++++++++ .../expectations/both/documentation.compat.c | 25 ++++++++++++++ tests/expectations/documentation.c | 17 ++++++++++ tests/expectations/documentation.compat.c | 25 ++++++++++++++ tests/expectations/documentation.cpp | 19 +++++++++++ tests/expectations/tag/associated_in_body.c | 1 + .../tag/associated_in_body.compat.c | 1 + tests/expectations/tag/bitflags.c | 1 + tests/expectations/tag/bitflags.compat.c | 1 + tests/expectations/tag/documentation.c | 17 ++++++++++ tests/expectations/tag/documentation.compat.c | 25 ++++++++++++++ tests/rust/documentation.rs | 12 +++++++ 24 files changed, 191 insertions(+), 16 deletions(-) create mode 100644 tests/expectations/both/documentation.c create mode 100644 tests/expectations/both/documentation.compat.c create mode 100644 tests/expectations/documentation.c create mode 100644 tests/expectations/documentation.compat.c create mode 100644 tests/expectations/documentation.cpp create mode 100644 tests/expectations/tag/documentation.c create mode 100644 tests/expectations/tag/documentation.compat.c create mode 100644 tests/rust/documentation.rs diff --git a/src/bindgen/ir/documentation.rs b/src/bindgen/ir/documentation.rs index 1a67b78..2ab7708 100644 --- a/src/bindgen/ir/documentation.rs +++ b/src/bindgen/ir/documentation.rs @@ -20,7 +20,7 @@ impl Documentation { let doc = attrs .get_comment_lines() .into_iter() - .filter(|x| !x.is_empty() && !x.starts_with("cbindgen:")) + .filter(|x| !x.starts_with("cbindgen:")) .collect(); Documentation { doc_comment: doc } diff --git a/src/bindgen/utilities.rs b/src/bindgen/utilities.rs index 23a4eb1..7485679 100644 --- a/src/bindgen/utilities.rs +++ b/src/bindgen/utilities.rs @@ -252,7 +252,7 @@ impl SynAttributeHelpers for [syn::Attribute] { } fn get_comment_lines(&self) -> Vec { - let mut comment_lines = Vec::new(); + let mut raw_comment = String::new(); for attr in self { if attr.style == syn::AttrStyle::Outer { @@ -263,26 +263,30 @@ impl SynAttributeHelpers for [syn::Attribute] { })) = attr.interpret_meta() { let name = ident.to_string(); - let comment = comment.value(); - if &*name == "doc" { - for raw in comment.lines() { - let line = raw - .trim_start_matches(" ") - .trim_start_matches("//") - .trim_start_matches("///") - .trim_start_matches("/**") - .trim_start_matches("/*") - .trim_start_matches("*/") - .trim_start_matches("*") - .trim_end(); - comment_lines.push(line.to_owned()); - } + let text = comment.value(); + raw_comment += &text; + raw_comment += "\n"; } } } } + let mut comment_lines = Vec::new(); + for raw in raw_comment.lines() { + let line = raw + .trim_start_matches(" ") + .trim_start_matches("//") + .trim_start_matches("///") + .trim_start_matches("/**") + .trim_start_matches("/*") + .trim_start_matches("*/") + .trim_start_matches("*") + .trim_end(); + + comment_lines.push(line.to_owned()); + } + comment_lines } } diff --git a/tests/expectations/associated_in_body.c b/tests/expectations/associated_in_body.c index 3b6caba..347c554 100644 --- a/tests/expectations/associated_in_body.c +++ b/tests/expectations/associated_in_body.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ typedef struct { diff --git a/tests/expectations/associated_in_body.compat.c b/tests/expectations/associated_in_body.compat.c index 698321d..42e77dc 100644 --- a/tests/expectations/associated_in_body.compat.c +++ b/tests/expectations/associated_in_body.compat.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ typedef struct { diff --git a/tests/expectations/associated_in_body.cpp b/tests/expectations/associated_in_body.cpp index d3cda8e..a11ff49 100644 --- a/tests/expectations/associated_in_body.cpp +++ b/tests/expectations/associated_in_body.cpp @@ -4,6 +4,7 @@ #include /// Constants shared by multiple CSS Box Alignment properties +/// /// These constants match Gecko's `NS_STYLE_ALIGN_*` constants. struct StyleAlignFlags { uint8_t bits; diff --git a/tests/expectations/bitflags.c b/tests/expectations/bitflags.c index 37fbb4e..05fdda1 100644 --- a/tests/expectations/bitflags.c +++ b/tests/expectations/bitflags.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ typedef struct { diff --git a/tests/expectations/bitflags.compat.c b/tests/expectations/bitflags.compat.c index a7e6f91..2f52f0c 100644 --- a/tests/expectations/bitflags.compat.c +++ b/tests/expectations/bitflags.compat.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ typedef struct { diff --git a/tests/expectations/bitflags.cpp b/tests/expectations/bitflags.cpp index 2197424..9c89fee 100644 --- a/tests/expectations/bitflags.cpp +++ b/tests/expectations/bitflags.cpp @@ -4,6 +4,7 @@ #include /// Constants shared by multiple CSS Box Alignment properties +/// /// These constants match Gecko's `NS_STYLE_ALIGN_*` constants. struct AlignFlags { uint8_t bits; diff --git a/tests/expectations/both/associated_in_body.c b/tests/expectations/both/associated_in_body.c index 9dc5007..33384c3 100644 --- a/tests/expectations/both/associated_in_body.c +++ b/tests/expectations/both/associated_in_body.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ typedef struct StyleAlignFlags { diff --git a/tests/expectations/both/associated_in_body.compat.c b/tests/expectations/both/associated_in_body.compat.c index 47dfb50..dcfd04a 100644 --- a/tests/expectations/both/associated_in_body.compat.c +++ b/tests/expectations/both/associated_in_body.compat.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ typedef struct StyleAlignFlags { diff --git a/tests/expectations/both/bitflags.c b/tests/expectations/both/bitflags.c index 9065677..fa0b509 100644 --- a/tests/expectations/both/bitflags.c +++ b/tests/expectations/both/bitflags.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ typedef struct AlignFlags { diff --git a/tests/expectations/both/bitflags.compat.c b/tests/expectations/both/bitflags.compat.c index b20a883..6e7f2fb 100644 --- a/tests/expectations/both/bitflags.compat.c +++ b/tests/expectations/both/bitflags.compat.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ typedef struct AlignFlags { diff --git a/tests/expectations/both/documentation.c b/tests/expectations/both/documentation.c new file mode 100644 index 0000000..c127e77 --- /dev/null +++ b/tests/expectations/both/documentation.c @@ -0,0 +1,17 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + * + * But at least it contains some more documentation as someone would expect + * from a simple test case like this. + * + * # Hint + * + * Always ensure that everything is properly documented, even if you feel lazy. + * Sometimes** it is also helpful to include some markdown formatting. + */ +void root(void); diff --git a/tests/expectations/both/documentation.compat.c b/tests/expectations/both/documentation.compat.c new file mode 100644 index 0000000..c1530de --- /dev/null +++ b/tests/expectations/both/documentation.compat.c @@ -0,0 +1,25 @@ +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif // __cplusplus + +/** + * The root of all evil. + * + * But at least it contains some more documentation as someone would expect + * from a simple test case like this. + * + * # Hint + * + * Always ensure that everything is properly documented, even if you feel lazy. + * Sometimes** it is also helpful to include some markdown formatting. + */ +void root(void); + +#ifdef __cplusplus +} // extern "C" +#endif // __cplusplus diff --git a/tests/expectations/documentation.c b/tests/expectations/documentation.c new file mode 100644 index 0000000..c127e77 --- /dev/null +++ b/tests/expectations/documentation.c @@ -0,0 +1,17 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + * + * But at least it contains some more documentation as someone would expect + * from a simple test case like this. + * + * # Hint + * + * Always ensure that everything is properly documented, even if you feel lazy. + * Sometimes** it is also helpful to include some markdown formatting. + */ +void root(void); diff --git a/tests/expectations/documentation.compat.c b/tests/expectations/documentation.compat.c new file mode 100644 index 0000000..c1530de --- /dev/null +++ b/tests/expectations/documentation.compat.c @@ -0,0 +1,25 @@ +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif // __cplusplus + +/** + * The root of all evil. + * + * But at least it contains some more documentation as someone would expect + * from a simple test case like this. + * + * # Hint + * + * Always ensure that everything is properly documented, even if you feel lazy. + * Sometimes** it is also helpful to include some markdown formatting. + */ +void root(void); + +#ifdef __cplusplus +} // extern "C" +#endif // __cplusplus diff --git a/tests/expectations/documentation.cpp b/tests/expectations/documentation.cpp new file mode 100644 index 0000000..564ba15 --- /dev/null +++ b/tests/expectations/documentation.cpp @@ -0,0 +1,19 @@ +#include +#include +#include +#include + +extern "C" { + +/// The root of all evil. +/// +/// But at least it contains some more documentation as someone would expect +/// from a simple test case like this. +/// +/// # Hint +/// +/// Always ensure that everything is properly documented, even if you feel lazy. +/// Sometimes** it is also helpful to include some markdown formatting. +void root(); + +} // extern "C" diff --git a/tests/expectations/tag/associated_in_body.c b/tests/expectations/tag/associated_in_body.c index b647805..31c9a12 100644 --- a/tests/expectations/tag/associated_in_body.c +++ b/tests/expectations/tag/associated_in_body.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ struct StyleAlignFlags { diff --git a/tests/expectations/tag/associated_in_body.compat.c b/tests/expectations/tag/associated_in_body.compat.c index e68c9b0..3c9846b 100644 --- a/tests/expectations/tag/associated_in_body.compat.c +++ b/tests/expectations/tag/associated_in_body.compat.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ struct StyleAlignFlags { diff --git a/tests/expectations/tag/bitflags.c b/tests/expectations/tag/bitflags.c index 1235f8d..600f1e0 100644 --- a/tests/expectations/tag/bitflags.c +++ b/tests/expectations/tag/bitflags.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ struct AlignFlags { diff --git a/tests/expectations/tag/bitflags.compat.c b/tests/expectations/tag/bitflags.compat.c index 4be144e..9fe7e74 100644 --- a/tests/expectations/tag/bitflags.compat.c +++ b/tests/expectations/tag/bitflags.compat.c @@ -5,6 +5,7 @@ /** * Constants shared by multiple CSS Box Alignment properties + * * These constants match Gecko's `NS_STYLE_ALIGN_*` constants. */ struct AlignFlags { diff --git a/tests/expectations/tag/documentation.c b/tests/expectations/tag/documentation.c new file mode 100644 index 0000000..c127e77 --- /dev/null +++ b/tests/expectations/tag/documentation.c @@ -0,0 +1,17 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + * + * But at least it contains some more documentation as someone would expect + * from a simple test case like this. + * + * # Hint + * + * Always ensure that everything is properly documented, even if you feel lazy. + * Sometimes** it is also helpful to include some markdown formatting. + */ +void root(void); diff --git a/tests/expectations/tag/documentation.compat.c b/tests/expectations/tag/documentation.compat.c new file mode 100644 index 0000000..c1530de --- /dev/null +++ b/tests/expectations/tag/documentation.compat.c @@ -0,0 +1,25 @@ +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif // __cplusplus + +/** + * The root of all evil. + * + * But at least it contains some more documentation as someone would expect + * from a simple test case like this. + * + * # Hint + * + * Always ensure that everything is properly documented, even if you feel lazy. + * Sometimes** it is also helpful to include some markdown formatting. + */ +void root(void); + +#ifdef __cplusplus +} // extern "C" +#endif // __cplusplus diff --git a/tests/rust/documentation.rs b/tests/rust/documentation.rs new file mode 100644 index 0000000..056e047 --- /dev/null +++ b/tests/rust/documentation.rs @@ -0,0 +1,12 @@ +/// The root of all evil. +/// +/// But at least it contains some more documentation as someone would expect +/// from a simple test case like this. +/// +/// # Hint +/// +/// Always ensure that everything is properly documented, even if you feel lazy. +/// **Sometimes** it is also helpful to include some markdown formatting. +#[no_mangle] +pub extern "C" fn root() { +}