Avoid trimming non whitespace characters.

0ndorio · emilio · commit 47e831753b46 · 2019-08-08T14:07:04.000+02:00
Rustc already removes all leading `/` symbols during the conversion from doc-comments into annotations. Any additional trimming of non whitespace characters just reduces the formatting flexibility of a comment. ... fixes mozilla#374
diff --git a/src/bindgen/utilities.rs b/src/bindgen/utilities.rs
@@ -252,41 +252,25 @@ impl SynAttributeHelpers for [syn::Attribute] {
     }
 
     fn get_comment_lines(&self) -> Vec<String> {
-        let mut raw_comment = String::new();
+        let mut comment = Vec::new();
 
         for attr in self {
             if attr.style == syn::AttrStyle::Outer {
                 if let Some(syn::Meta::NameValue(syn::MetaNameValue {
                     ident,
-                    lit: syn::Lit::Str(comment),
+                    lit: syn::Lit::Str(content),
                     ..
                 })) = attr.interpret_meta()
                 {
                     let name = ident.to_string();
                     if &*name == "doc" {
-                        let text = comment.value();
-                        raw_comment += &text;
-                        raw_comment += "\n";
+                        let text = content.value().trim().to_owned();
+                        comment.push(text);
                     }
                 }
             }
         }
 
-        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
+        comment
     }
 }
diff --git a/tests/expectations/both/documentation.c b/tests/expectations/both/documentation.c
@@ -12,6 +12,14 @@
  * # Hint
  *
  * Always ensure that everything is properly documented, even if you feel lazy.
- * Sometimes** it is also helpful to include some markdown formatting.
+ * **Sometimes** it is also helpful to include some markdown formatting.
+ *
+ * ////////////////////////////////////////////////////////////////////////////
+ *
+ * # Attention
+ *
+ * Rust is going to trim all leading `/` symbols. If you want to use them as a
+ * marker you need to add at least a single whitespace inbetween the tripple
+ * slash doc-comment marker and the rest.
  */
 void root(void);
diff --git a/tests/expectations/both/documentation.compat.c b/tests/expectations/both/documentation.compat.c
@@ -16,7 +16,15 @@ extern "C" {
  * # Hint
  *
  * Always ensure that everything is properly documented, even if you feel lazy.
- * Sometimes** it is also helpful to include some markdown formatting.
+ * **Sometimes** it is also helpful to include some markdown formatting.
+ *
+ * ////////////////////////////////////////////////////////////////////////////
+ *
+ * # Attention
+ *
+ * Rust is going to trim all leading `/` symbols. If you want to use them as a
+ * marker you need to add at least a single whitespace inbetween the tripple
+ * slash doc-comment marker and the rest.
  */
 void root(void);
 
diff --git a/tests/expectations/documentation.c b/tests/expectations/documentation.c
@@ -12,6 +12,14 @@
  * # Hint
  *
  * Always ensure that everything is properly documented, even if you feel lazy.
- * Sometimes** it is also helpful to include some markdown formatting.
+ * **Sometimes** it is also helpful to include some markdown formatting.
+ *
+ * ////////////////////////////////////////////////////////////////////////////
+ *
+ * # Attention
+ *
+ * Rust is going to trim all leading `/` symbols. If you want to use them as a
+ * marker you need to add at least a single whitespace inbetween the tripple
+ * slash doc-comment marker and the rest.
  */
 void root(void);
diff --git a/tests/expectations/documentation.compat.c b/tests/expectations/documentation.compat.c
@@ -16,7 +16,15 @@ extern "C" {
  * # Hint
  *
  * Always ensure that everything is properly documented, even if you feel lazy.
- * Sometimes** it is also helpful to include some markdown formatting.
+ * **Sometimes** it is also helpful to include some markdown formatting.
+ *
+ * ////////////////////////////////////////////////////////////////////////////
+ *
+ * # Attention
+ *
+ * Rust is going to trim all leading `/` symbols. If you want to use them as a
+ * marker you need to add at least a single whitespace inbetween the tripple
+ * slash doc-comment marker and the rest.
  */
 void root(void);
 
diff --git a/tests/expectations/documentation.cpp b/tests/expectations/documentation.cpp
@@ -13,7 +13,15 @@ extern "C" {
 /// # Hint
 ///
 /// Always ensure that everything is properly documented, even if you feel lazy.
-/// Sometimes** it is also helpful to include some markdown formatting.
+/// **Sometimes** it is also helpful to include some markdown formatting.
+///
+/// ////////////////////////////////////////////////////////////////////////////
+///
+/// # Attention
+///
+/// Rust is going to trim all leading `/` symbols. If you want to use them as a
+/// marker you need to add at least a single whitespace inbetween the tripple
+/// slash doc-comment marker and the rest.
 void root();
 
 } // extern "C"
diff --git a/tests/expectations/tag/documentation.c b/tests/expectations/tag/documentation.c
@@ -12,6 +12,14 @@
  * # Hint
  *
  * Always ensure that everything is properly documented, even if you feel lazy.
- * Sometimes** it is also helpful to include some markdown formatting.
+ * **Sometimes** it is also helpful to include some markdown formatting.
+ *
+ * ////////////////////////////////////////////////////////////////////////////
+ *
+ * # Attention
+ *
+ * Rust is going to trim all leading `/` symbols. If you want to use them as a
+ * marker you need to add at least a single whitespace inbetween the tripple
+ * slash doc-comment marker and the rest.
  */
 void root(void);
diff --git a/tests/expectations/tag/documentation.compat.c b/tests/expectations/tag/documentation.compat.c
@@ -16,7 +16,15 @@ extern "C" {
  * # Hint
  *
  * Always ensure that everything is properly documented, even if you feel lazy.
- * Sometimes** it is also helpful to include some markdown formatting.
+ * **Sometimes** it is also helpful to include some markdown formatting.
+ *
+ * ////////////////////////////////////////////////////////////////////////////
+ *
+ * # Attention
+ *
+ * Rust is going to trim all leading `/` symbols. If you want to use them as a
+ * marker you need to add at least a single whitespace inbetween the tripple
+ * slash doc-comment marker and the rest.
  */
 void root(void);
 
diff --git a/tests/rust/documentation.rs b/tests/rust/documentation.rs
@@ -7,6 +7,14 @@
 ///
 /// Always ensure that everything is properly documented, even if you feel lazy.
 /// **Sometimes** it is also helpful to include some markdown formatting.
+///
+/// ////////////////////////////////////////////////////////////////////////////
+///
+/// # Attention
+///
+/// Rust is going to trim all leading `/` symbols. If you want to use them as a
+/// marker you need to add at least a single whitespace inbetween the tripple
+/// slash doc-comment marker and the rest.
 #[no_mangle]
 pub extern "C" fn root() {
 }

Original file line number	Diff line number	Diff line change
`@@ -252,41 +252,25 @@ impl SynAttributeHelpers for [syn::Attribute] {`
`252`	`252`	`}`
`253`	`253`
`254`	`254`	`fn get_comment_lines(&self) -> Vec<String> {`
`255`		`- let mut raw_comment = String::new();`
	`255`	`+ let mut comment = Vec::new();`
`256`	`256`
`257`	`257`	`for attr in self {`
`258`	`258`	`if attr.style == syn::AttrStyle::Outer {`
`259`	`259`	`if let Some(syn::Meta::NameValue(syn::MetaNameValue {`
`260`	`260`	`ident,`
`261`		`- lit: syn::Lit::Str(comment),`
	`261`	`+ lit: syn::Lit::Str(content),`
`262`	`262`	`..`
`263`	`263`	`})) = attr.interpret_meta()`
`264`	`264`	`{`
`265`	`265`	`let name = ident.to_string();`
`266`	`266`	`if &*name == "doc" {`
`267`		`- let text = comment.value();`
`268`		`- raw_comment += &text;`
`269`		`- raw_comment += "\n";`
	`267`	`+ let text = content.value().trim().to_owned();`
	`268`	`+ comment.push(text);`
`270`	`269`	`}`
`271`	`270`	`}`
`272`	`271`	`}`
`273`	`272`	`}`
`274`	`273`
`275`		`- let mut comment_lines = Vec::new();`
`276`		`- for raw in raw_comment.lines() {`
`277`		`- let line = raw`
`278`		`- .trim_start_matches(" ")`
`279`		`- .trim_start_matches("//")`
`280`		`- .trim_start_matches("///")`
`281`		`- .trim_start_matches("/**")`
`282`		`- .trim_start_matches("/*")`
`283`		`- .trim_start_matches("*/")`
`284`		`- .trim_start_matches("*")`
`285`		`- .trim_end();`
`286`		`-`
`287`		`- comment_lines.push(line.to_owned());`
`288`		`- }`
`289`		`-`
`290`		`- comment_lines`
	`274`	`+ comment`
`291`	`275`	`}`
`292`	`276`	`}`