Add more documentation style options (#305)

* Ignoring IDE files.

* Addresses issue #302, also amends #59 insofar that vanilla C-style now does not prefix individual lines with `*` anymore.

* Removed Javadoc reference.

* Renamed `Doxylight` to `Doxy` and changed C default to that.

* Added documentation.

* Changed enum name and applied `fmt`.

* Fixed comment.

* Fixed match.

.gitignore

@@ -1 +1,3 @@
 target
+.idea
+.vscode

README.md

@@ -104,6 +104,10 @@ tab_width = 2
 language = "[C|C++]"
 # A rule to use to select style of declaration in C, tagname vs typedef
 style = "[Both|Type|Tag]"
+# How the generated documentation should be commented.
+# C uses /* */; C++ uses //; Doxy is like C but with leading * per line.
+documentation_style = "[C, C++, Doxy]"
+
 
 [defines]
 # A rule for generating `#ifdef`s for matching `#[cfg]`ed items,

src/bindgen/config.rs

@@ -100,6 +100,32 @@ impl FromStr for Layout {
 
 deserialize_enum_str!(Layout);
 
+/// How the comments containing documentation should be styled.
+#[derive(Debug, Clone, PartialEq, Copy)]
+pub enum DocumentationStyle {
+    C,
+    Doxy,
+    Cxx,
+    Auto,
+}
+
+impl FromStr for DocumentationStyle {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<DocumentationStyle, Self::Err> {
+        match s.to_lowercase().as_ref() {
+            "c" => Ok(DocumentationStyle::C),
+            "cxx" => Ok(DocumentationStyle::Cxx),
+            "c++" => Ok(DocumentationStyle::Cxx),
+            "doxy" => Ok(DocumentationStyle::Doxy),
+            "auto" => Ok(DocumentationStyle::Auto),
+            _ => Err(format!("Unrecognized documentation style: '{}'.", s)),
+        }
+    }
+}
+
+deserialize_enum_str!(DocumentationStyle);
+
 /// A style of Style to use when generating structs and enums.
 #[derive(Debug, Clone, PartialEq)]
 pub enum Style {
@@ -597,6 +623,8 @@ pub struct Config {
     pub defines: HashMap<String, String>,
     /// Include doc comments from rust as documentation
     pub documentation: bool,
+    /// How documentation comments should be styled.
+    pub documentation_style: DocumentationStyle,
 }
 
 impl Default for Config {
@@ -626,6 +654,7 @@ impl Default for Config {
             constant: ConstantConfig::default(),
             defines: HashMap::new(),
             documentation: true,
+            documentation_style: DocumentationStyle::Auto,
         }
     }
 }

src/bindgen/ir/documentation.rs

@@ -6,7 +6,7 @@ use std::io::Write;
 
 use syn;
 
-use bindgen::config::{Config, Language};
+use bindgen::config::{Config, DocumentationStyle, Language};
 use bindgen::utilities::SynAttributeHelpers;
 use bindgen::writer::{Source, SourceWriter};
 
@@ -39,25 +39,57 @@ impl Source for Documentation {
             return;
         }
 
-        if config.language == Language::C {
-            out.write("/**");
-            out.new_line();
-        }
-        for line in &self.doc_comment {
-            if config.language != Language::C {
-                out.write("///");
-            } else {
-                out.write(" *");
+        let style = match config.documentation_style {
+            DocumentationStyle::Auto if config.language == Language::C => DocumentationStyle::Doxy,
+            DocumentationStyle::Auto if config.language == Language::Cxx => DocumentationStyle::Cxx,
+            DocumentationStyle::Auto => DocumentationStyle::C, // Fallback if `Language` gets extended.
+            other => other,
+        };
+
+        // Following these documents for style conventions:
+        // https://en.wikibooks.org/wiki/C++_Programming/Code/Style_Conventions/Comments
+        // https://www.cs.cmu.edu/~410/doc/doxygen.html
+        match style {
+            DocumentationStyle::C => {
+                out.write("/*");
+                out.new_line();
             }
+
+            DocumentationStyle::Doxy => {
+                out.write("/**");
+                out.new_line();
+            }
+
+            _ => (),
+        }
+
+        for line in &self.doc_comment {
+            match style {
+                DocumentationStyle::C => out.write(""),
+                DocumentationStyle::Doxy => out.write(" *"),
+                DocumentationStyle::Cxx => out.write("///"),
+                DocumentationStyle::Auto => unreachable!(), // Auto case should always be covered
+            }
+
             if line.len() != 0 {
                 out.write(" ");
             }
             write!(out, "{}", line);
             out.new_line();
         }
-        if config.language == Language::C {
-            out.write(" */");
-            out.new_line();
+
+        match style {
+            DocumentationStyle::C => {
+                out.write(" */");
+                out.new_line();
+            }
+
+            DocumentationStyle::Doxy => {
+                out.write(" */");
+                out.new_line();
+            }
+
+            _ => (),
         }
     }
 }

tests/expectations/both/docstyle_auto.c

@@ -0,0 +1,9 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * The root of all evil.
+ */
+void root(void);

tests/expectations/both/docstyle_doxy.c

@@ -0,0 +1,9 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * The root of all evil.
+ */
+void root(void);

tests/expectations/both/docstyle_doxylight.c

@@ -0,0 +1,9 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * The root of all evil.
+ */
+void root(void);

tests/expectations/docstyle_auto.c

@@ -0,0 +1,9 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * The root of all evil.
+ */
+void root(void);

tests/expectations/docstyle_auto.cpp

@@ -0,0 +1,10 @@
+#include <cstdarg>
+#include <cstdint>
+#include <cstdlib>
+
+extern "C" {
+
+/// The root of all evil.
+void root();
+
+} // extern "C"

tests/expectations/docstyle_doxy.c

@@ -0,0 +1,9 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * The root of all evil.
+ */
+void root(void);

tests/expectations/docstyle_doxy.cpp

@@ -0,0 +1,12 @@
+#include <cstdarg>
+#include <cstdint>
+#include <cstdlib>
+
+extern "C" {
+
+/**
+ * The root of all evil.
+ */
+void root();
+
+} // extern "C"

tests/expectations/docstyle_doxylight.c

@@ -0,0 +1,9 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * The root of all evil.
+ */
+void root(void);

tests/expectations/docstyle_doxylight.cpp

@@ -0,0 +1,12 @@
+#include <cstdarg>
+#include <cstdint>
+#include <cstdlib>
+
+extern "C" {
+
+/**
+ * The root of all evil.
+ */
+void root();
+
+} // extern "C"

tests/expectations/tag/docstyle_auto.c

@@ -0,0 +1,9 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * The root of all evil.
+ */
+void root(void);

tests/expectations/tag/docstyle_doxy.c

@@ -0,0 +1,9 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * The root of all evil.
+ */
+void root(void);

tests/expectations/tag/docstyle_doxylight.c

@@ -0,0 +1,9 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * The root of all evil.
+ */
+void root(void);

tests/rust/docstyle_auto.rs

@@ -0,0 +1,4 @@
+/// The root of all evil.
+#[no_mangle]
+pub extern "C" fn root() {
+}

tests/rust/docstyle_auto.toml

@@ -0,0 +1 @@
+documentation_style = "auto"

tests/rust/docstyle_doxy.rs

@@ -0,0 +1,4 @@
+/// The root of all evil.
+#[no_mangle]
+pub extern "C" fn root() {
+}

tests/rust/docstyle_doxy.toml

@@ -0,0 +1 @@
+documentation_style = "doxy"