From 51aff0a119a4da7c1b876300351ac1d483b09267 Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Sun, 24 Mar 2019 20:56:17 +0100 Subject: [PATCH] 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 | 2 + README.md | 6 +- src/bindgen/config.rs | 29 ++++++++++ src/bindgen/ir/documentation.rs | 58 +++++++++++++++----- tests/expectations/both/docstyle_auto.c | 9 +++ tests/expectations/both/docstyle_doxy.c | 9 +++ tests/expectations/both/docstyle_doxylight.c | 9 +++ tests/expectations/docstyle_auto.c | 9 +++ tests/expectations/docstyle_auto.cpp | 10 ++++ tests/expectations/docstyle_doxy.c | 9 +++ tests/expectations/docstyle_doxy.cpp | 12 ++++ tests/expectations/docstyle_doxylight.c | 9 +++ tests/expectations/docstyle_doxylight.cpp | 12 ++++ tests/expectations/tag/docstyle_auto.c | 9 +++ tests/expectations/tag/docstyle_doxy.c | 9 +++ tests/expectations/tag/docstyle_doxylight.c | 9 +++ tests/rust/docstyle_auto.rs | 4 ++ tests/rust/docstyle_auto.toml | 1 + tests/rust/docstyle_doxy.rs | 4 ++ tests/rust/docstyle_doxy.toml | 1 + 20 files changed, 206 insertions(+), 14 deletions(-) create mode 100644 tests/expectations/both/docstyle_auto.c create mode 100644 tests/expectations/both/docstyle_doxy.c create mode 100644 tests/expectations/both/docstyle_doxylight.c create mode 100644 tests/expectations/docstyle_auto.c create mode 100644 tests/expectations/docstyle_auto.cpp create mode 100644 tests/expectations/docstyle_doxy.c create mode 100644 tests/expectations/docstyle_doxy.cpp create mode 100644 tests/expectations/docstyle_doxylight.c create mode 100644 tests/expectations/docstyle_doxylight.cpp create mode 100644 tests/expectations/tag/docstyle_auto.c create mode 100644 tests/expectations/tag/docstyle_doxy.c create mode 100644 tests/expectations/tag/docstyle_doxylight.c create mode 100644 tests/rust/docstyle_auto.rs create mode 100644 tests/rust/docstyle_auto.toml create mode 100644 tests/rust/docstyle_doxy.rs create mode 100644 tests/rust/docstyle_doxy.toml diff --git a/.gitignore b/.gitignore index eb5a316..83fe80e 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ target +.idea +.vscode diff --git a/README.md b/README.md index c990f7f..6098ebd 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ This project can be used to generate C bindings for Rust code. It is currently b * Support for generating `#ifdef`'s for `#[cfg]` attributes * Support for `#[repr(sized)]` tagged enum's -## Installation +## Installation ``` cargo install cbindgen @@ -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, diff --git a/src/bindgen/config.rs b/src/bindgen/config.rs index 67f7d27..77e4e5b 100644 --- a/src/bindgen/config.rs +++ b/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 { + 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, /// 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, } } } diff --git a/src/bindgen/ir/documentation.rs b/src/bindgen/ir/documentation.rs index 9aa561b..a0a4224 100644 --- a/src/bindgen/ir/documentation.rs +++ b/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(); + } + + _ => (), } } } diff --git a/tests/expectations/both/docstyle_auto.c b/tests/expectations/both/docstyle_auto.c new file mode 100644 index 0000000..86bcd0c --- /dev/null +++ b/tests/expectations/both/docstyle_auto.c @@ -0,0 +1,9 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + */ +void root(void); diff --git a/tests/expectations/both/docstyle_doxy.c b/tests/expectations/both/docstyle_doxy.c new file mode 100644 index 0000000..86bcd0c --- /dev/null +++ b/tests/expectations/both/docstyle_doxy.c @@ -0,0 +1,9 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + */ +void root(void); diff --git a/tests/expectations/both/docstyle_doxylight.c b/tests/expectations/both/docstyle_doxylight.c new file mode 100644 index 0000000..86bcd0c --- /dev/null +++ b/tests/expectations/both/docstyle_doxylight.c @@ -0,0 +1,9 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + */ +void root(void); diff --git a/tests/expectations/docstyle_auto.c b/tests/expectations/docstyle_auto.c new file mode 100644 index 0000000..86bcd0c --- /dev/null +++ b/tests/expectations/docstyle_auto.c @@ -0,0 +1,9 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + */ +void root(void); diff --git a/tests/expectations/docstyle_auto.cpp b/tests/expectations/docstyle_auto.cpp new file mode 100644 index 0000000..ea014d0 --- /dev/null +++ b/tests/expectations/docstyle_auto.cpp @@ -0,0 +1,10 @@ +#include +#include +#include + +extern "C" { + +/// The root of all evil. +void root(); + +} // extern "C" diff --git a/tests/expectations/docstyle_doxy.c b/tests/expectations/docstyle_doxy.c new file mode 100644 index 0000000..86bcd0c --- /dev/null +++ b/tests/expectations/docstyle_doxy.c @@ -0,0 +1,9 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + */ +void root(void); diff --git a/tests/expectations/docstyle_doxy.cpp b/tests/expectations/docstyle_doxy.cpp new file mode 100644 index 0000000..48127b3 --- /dev/null +++ b/tests/expectations/docstyle_doxy.cpp @@ -0,0 +1,12 @@ +#include +#include +#include + +extern "C" { + +/** + * The root of all evil. + */ +void root(); + +} // extern "C" diff --git a/tests/expectations/docstyle_doxylight.c b/tests/expectations/docstyle_doxylight.c new file mode 100644 index 0000000..86bcd0c --- /dev/null +++ b/tests/expectations/docstyle_doxylight.c @@ -0,0 +1,9 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + */ +void root(void); diff --git a/tests/expectations/docstyle_doxylight.cpp b/tests/expectations/docstyle_doxylight.cpp new file mode 100644 index 0000000..48127b3 --- /dev/null +++ b/tests/expectations/docstyle_doxylight.cpp @@ -0,0 +1,12 @@ +#include +#include +#include + +extern "C" { + +/** + * The root of all evil. + */ +void root(); + +} // extern "C" diff --git a/tests/expectations/tag/docstyle_auto.c b/tests/expectations/tag/docstyle_auto.c new file mode 100644 index 0000000..86bcd0c --- /dev/null +++ b/tests/expectations/tag/docstyle_auto.c @@ -0,0 +1,9 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + */ +void root(void); diff --git a/tests/expectations/tag/docstyle_doxy.c b/tests/expectations/tag/docstyle_doxy.c new file mode 100644 index 0000000..86bcd0c --- /dev/null +++ b/tests/expectations/tag/docstyle_doxy.c @@ -0,0 +1,9 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + */ +void root(void); diff --git a/tests/expectations/tag/docstyle_doxylight.c b/tests/expectations/tag/docstyle_doxylight.c new file mode 100644 index 0000000..86bcd0c --- /dev/null +++ b/tests/expectations/tag/docstyle_doxylight.c @@ -0,0 +1,9 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + */ +void root(void); diff --git a/tests/rust/docstyle_auto.rs b/tests/rust/docstyle_auto.rs new file mode 100644 index 0000000..2b66147 --- /dev/null +++ b/tests/rust/docstyle_auto.rs @@ -0,0 +1,4 @@ +/// The root of all evil. +#[no_mangle] +pub extern "C" fn root() { +} diff --git a/tests/rust/docstyle_auto.toml b/tests/rust/docstyle_auto.toml new file mode 100644 index 0000000..be9e72e --- /dev/null +++ b/tests/rust/docstyle_auto.toml @@ -0,0 +1 @@ +documentation_style = "auto" diff --git a/tests/rust/docstyle_doxy.rs b/tests/rust/docstyle_doxy.rs new file mode 100644 index 0000000..2b66147 --- /dev/null +++ b/tests/rust/docstyle_doxy.rs @@ -0,0 +1,4 @@ +/// The root of all evil. +#[no_mangle] +pub extern "C" fn root() { +} diff --git a/tests/rust/docstyle_doxy.toml b/tests/rust/docstyle_doxy.toml new file mode 100644 index 0000000..05e606a --- /dev/null +++ b/tests/rust/docstyle_doxy.toml @@ -0,0 +1 @@ +documentation_style = "doxy"