Preserve empty lines in doc comments.

0ndorio · emilio · commit b4b82a500cf5 · 2019-08-03T17:38:59.000+02:00
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.
diff --git 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
@@ -252,7 +252,7 @@ impl SynAttributeHelpers for [syn::Attribute] {
     }
 
     fn get_comment_lines(&self) -> Vec<String> {
-        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
@@ -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
@@ -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
@@ -4,6 +4,7 @@
 #include <new>
 
 /// 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
@@ -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
@@ -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
@@ -4,6 +4,7 @@
 #include <new>
 
 /// 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,17 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * 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
@@ -0,0 +1,25 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#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
@@ -0,0 +1,17 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * 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
@@ -0,0 +1,25 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#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
@@ -0,0 +1,19 @@
+#include <cstdarg>
+#include <cstdint>
+#include <cstdlib>
+#include <new>
+
+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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,17 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * 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
@@ -0,0 +1,25 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#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
@@ -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() {
+}
