Intelligently convert C/C++ comments to Rust

With this change, we can correctly parse C++ block comments.

```
/**
 * Does a thing
 *
 * More documentation. This test does something
 * useful.
 */
```

into

```
/// Does a thing
///
/// More documentation. This test does something
/// useful.
```

Fixes rust-lang#426.

Author: dylanmckay

build.rs

@@ -11,6 +11,7 @@ mod codegen {
         let dst = Path::new(&out_dir).join("codegen.rs");
 
         quasi_codegen::expand(&src, &dst).unwrap();
+        println!("cargo:rerun-if-changed=src/codegen/comment.rs");
         println!("cargo:rerun-if-changed=src/codegen/mod.rs");
         println!("cargo:rerun-if-changed=src/codegen/error.rs");
         println!("cargo:rerun-if-changed=src/codegen/helpers.rs");

src/codegen/comment.rs

@@ -0,0 +1,94 @@
+/// The type of a comment.
+#[derive(Debug, PartialEq, Eq)]
+enum Kind {
+    /// A `///` comment, or something of the like.
+    /// All lines in a comment should start with the same symbol.
+    SingleLines,
+    /// A `/**` comment, where each other line can start with `*` and the
+    /// entire block ends with `*/`.
+    MultiLine,
+}
+
+/// Checks if a comment should be emitted as a Rust doc comment.
+pub fn is_doc(comment: &str) -> bool {
+    self::kind(comment).is_some()
+}
+
+/// Gets the kind of the doc comment, if it is one.
+fn kind(comment: &str) -> Option<Kind> {
+    if comment.starts_with("/**") {
+        Some(Kind::MultiLine)
+    } else if comment.starts_with("///") {
+        Some(Kind::SingleLines)
+    } else {
+        None
+    }
+}
+
+/// Preprocesses a C/C++ comment so that it is a valid Rust comment.
+pub fn preprocess(comment: &str) -> String {
+    match self::kind(comment) {
+        Some(Kind::SingleLines) => preprocess_single_lines(comment),
+        Some(Kind::MultiLine) => preprocess_multi_line(comment),
+        None => panic!("comment is not a doc comment"),
+    }
+}
+
+fn preprocess_single_lines(comment: &str) -> String {
+    assert!(comment.starts_with("///"), "comment is not single line");
+    // We don't need to amend the comment because each line already
+    // starts with `///`.
+    comment.to_owned()
+}
+
+fn preprocess_multi_line(comment: &str) -> String {
+    let comment = comment.trim_left_matches("/")
+                         .trim_right_matches("/")
+                         .trim_right_matches("*")
+                         .trim();
+
+    // Strip any potential `*` characters preceding each line.
+    let mut lines: Vec<_> = comment.lines()
+        .map(|line| line.trim().trim_left_matches('*').trim())
+        .skip_while(|line| line.is_empty()) // Skip the first empty lines.
+        .map(|line| format!("/// {}", line))
+        .collect();
+
+    // Remove the trailing `*/`.
+    let last_idx = lines.len() - 1;
+    if lines[last_idx].is_empty() {
+        lines.remove(last_idx);
+    }
+
+    lines.join("\n")
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn ignores_non_doc_comments() {
+        assert_eq!(kind("// hello"), None);
+    }
+
+    #[test]
+    fn picks_up_single_and_multi_line_doc_comments() {
+        assert_eq!(kind("/// hello"), Some(Kind::SingleLines));
+        assert_eq!(kind("/** world */"), Some(Kind::MultiLine));
+    }
+
+    #[test]
+    fn processes_single_lines_correctly() {
+        assert_eq!(preprocess("/// hello"), "/// hello");
+    }
+
+    #[test]
+    fn processes_multi_lines_correctly() {
+        assert_eq!(preprocess("/** hello \n * world \n * foo \n */"),
+                   "/// hello\n/// world\n/// foo");
+
+        assert_eq!(preprocess("/**\nhello\n*world\n*foo\n*/"),
+                   "/// hello\n/// world\n/// foo");
+    }
+}

src/codegen/helpers.rs

@@ -30,7 +30,7 @@ pub mod attributes {
         aster::AstBuilder::new().attr().word("inline")
     }
 
-    pub fn doc(comment: &str) -> ast::Attribute {
+    pub fn comment(comment: &str) -> ast::Attribute {
         aster::AstBuilder::new().attr().doc(comment)
     }
 

src/codegen/mod.rs

@@ -1,5 +1,6 @@
 mod error;
 mod helpers;
+mod comment;
 pub mod struct_layout;
 
 use self::helpers::{BlobTyBuilder, attributes};
@@ -618,7 +619,10 @@ impl CodeGenerator for Type {
 
                 if ctx.options().generate_comments {
                     if let Some(comment) = item.comment() {
-                        typedef = typedef.attr().doc(comment);
+                        if comment::is_doc(comment) {
+                            typedef = typedef.attr()
+                                .doc(&comment::preprocess(comment)[..]);
+                        }
                     }
                 }
 
@@ -946,7 +950,9 @@ impl<'a> FieldCodegen<'a> for FieldData {
         let mut attrs = vec![];
         if ctx.options().generate_comments {
             if let Some(comment) = self.comment() {
-                attrs.push(attributes::doc(comment));
+                if comment::is_doc(comment) {
+                    attrs.push(attributes::comment(&comment::preprocess(comment)[..]));
+                }
             }
         }
 
@@ -1411,7 +1417,9 @@ impl CodeGenerator for CompInfo {
         let mut needs_default_impl = false;
         if ctx.options().generate_comments {
             if let Some(comment) = item.comment() {
-                attributes.push(attributes::doc(comment));
+                if comment::is_doc(comment) {
+                    attributes.push(attributes::comment(&comment::preprocess(comment)[..]));
+                }
             }
         }
         if self.packed() {
@@ -2359,7 +2367,10 @@ impl CodeGenerator for Enum {
 
         if ctx.options().generate_comments {
             if let Some(comment) = item.comment() {
-                builder = builder.with_attr(attributes::doc(comment));
+                if comment::is_doc(comment) {
+                    builder = builder.with_attr(
+                        attributes::comment(&comment::preprocess(comment)[..]));
+                }
             }
         }
 
@@ -3061,7 +3072,9 @@ impl CodeGenerator for Function {
 
         if ctx.options().generate_comments {
             if let Some(comment) = item.comment() {
-                attributes.push(attributes::doc(comment));
+                if comment::is_doc(comment) {
+                    attributes.push(attributes::comment(&comment::preprocess(comment)[..]));
+                }
             }
         }
 

tests/expectations/tests/accessors.rs

@@ -8,11 +8,11 @@
 #[derive(Debug, Default, Copy)]
 pub struct SomeAccessors {
     pub mNoAccessor: ::std::os::raw::c_int,
-    /** <div rustbindgen accessor></div> */
+    /// <div rustbindgen accessor></div>
     pub mBothAccessors: ::std::os::raw::c_int,
-    /** <div rustbindgen accessor="unsafe"></div> */
+    /// <div rustbindgen accessor="unsafe"></div>
     pub mUnsafeAccessors: ::std::os::raw::c_int,
-    /** <div rustbindgen accessor="immutable"></div> */
+    /// <div rustbindgen accessor="immutable"></div>
     pub mImmutableAccessor: ::std::os::raw::c_int,
 }
 #[test]
@@ -68,7 +68,7 @@ impl SomeAccessors {
         &self.mImmutableAccessor
     }
 }
-/** <div rustbindgen accessor></div> */
+/// <div rustbindgen accessor></div>
 #[repr(C)]
 #[derive(Debug, Default, Copy)]
 pub struct AllAccessors {
@@ -114,7 +114,7 @@ impl AllAccessors {
         &mut self.mAlsoBothAccessors
     }
 }
-/** <div rustbindgen accessor="unsafe"></div> */
+/// <div rustbindgen accessor="unsafe"></div>
 #[repr(C)]
 #[derive(Debug, Default, Copy)]
 pub struct AllUnsafeAccessors {
@@ -162,16 +162,16 @@ impl AllUnsafeAccessors {
         &mut self.mAlsoBothAccessors
     }
 }
-/** <div rustbindgen accessor></div> */
+/// <div rustbindgen accessor></div>
 #[repr(C)]
 #[derive(Debug, Default, Copy)]
 pub struct ContradictAccessors {
     pub mBothAccessors: ::std::os::raw::c_int,
-    /** <div rustbindgen accessor="false"></div> */
+    /// <div rustbindgen accessor="false"></div>
     pub mNoAccessors: ::std::os::raw::c_int,
-    /** <div rustbindgen accessor="unsafe"></div> */
+    /// <div rustbindgen accessor="unsafe"></div>
     pub mUnsafeAccessors: ::std::os::raw::c_int,
-    /** <div rustbindgen accessor="immutable"></div> */
+    /// <div rustbindgen accessor="immutable"></div>
     pub mImmutableAccessor: ::std::os::raw::c_int,
 }
 #[test]
@@ -229,7 +229,7 @@ impl ContradictAccessors {
         &self.mImmutableAccessor
     }
 }
-/** <div rustbindgen accessor replaces="Replaced"></div> */
+/// <div rustbindgen accessor replaces="Replaced"></div>
 #[repr(C)]
 #[derive(Debug, Default, Copy)]
 pub struct Replaced {
@@ -258,7 +258,7 @@ impl Replaced {
         &mut self.mAccessor
     }
 }
-/** <div rustbindgen accessor></div> */
+/// <div rustbindgen accessor></div>
 #[repr(C)]
 #[derive(Debug, Default, Copy)]
 pub struct Wrapper {

tests/expectations/tests/annotation_hide.rs

@@ -4,9 +4,7 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
 
 
-/**
- * <div rustbindgen opaque></div>
- */
+/// <div rustbindgen opaque></div>
 #[repr(C)]
 #[derive(Debug, Default, Copy)]
 pub struct D {

tests/expectations/tests/class_use_as.rs

@@ -4,9 +4,7 @@
 #![allow(dead_code, non_snake_case, non_camel_case_types, non_upper_case_globals)]
 
 
-/**
- * <div rustbindgen="true" replaces="whatever"></div>
- */
+/// <div rustbindgen="true" replaces="whatever"></div>
 #[repr(C)]
 #[derive(Debug, Default, Copy)]
 pub struct whatever {