From 0e3f9bd9cb6a301311d215fa3637964a41bd15fc Mon Sep 17 00:00:00 2001 From: Sean McArthur Date: Wed, 15 Sep 2021 17:25:12 -0700 Subject: [PATCH] Add documentation_style to with short and full options --- docs.md | 9 ++++++++ src/bindgen/config.rs | 24 +++++++++++++++++++++ src/bindgen/ir/documentation.rs | 9 ++++++-- template.toml | 1 + tests/expectations/doclength_short.c | 14 ++++++++++++ tests/expectations/doclength_short.compat.c | 22 +++++++++++++++++++ tests/expectations/doclength_short.cpp | 15 +++++++++++++ tests/expectations/doclength_short.pyx | 20 +++++++++++++++++ tests/rust/doclength_short.rs | 16 ++++++++++++++ tests/rust/doclength_short.toml | 1 + tests/tests.rs | 4 ++++ 11 files changed, 133 insertions(+), 2 deletions(-) create mode 100644 tests/expectations/doclength_short.c create mode 100644 tests/expectations/doclength_short.compat.c create mode 100644 tests/expectations/doclength_short.cpp create mode 100644 tests/expectations/doclength_short.pyx create mode 100644 tests/rust/doclength_short.rs create mode 100644 tests/rust/doclength_short.toml diff --git a/docs.md b/docs.md index 726ee8382..187b33b84 100644 --- a/docs.md +++ b/docs.md @@ -500,6 +500,15 @@ documentation = true # default: "auto" documentation_style = "doxy" +# How much of the documentation for each item is output. +# +# possible values: +# * "short": Only the first line. +# * "full": The full documentation. +# +# default: "full" +documentation_style = "short" + diff --git a/src/bindgen/config.rs b/src/bindgen/config.rs index acfc2ead3..3560bb2c9 100644 --- a/src/bindgen/config.rs +++ b/src/bindgen/config.rs @@ -191,6 +191,27 @@ impl FromStr for DocumentationStyle { deserialize_enum_str!(DocumentationStyle); +/// How much of the documentation to include in the header file. +#[derive(Debug, Clone, Copy)] +pub enum DocumentationLength { + Short, + Full, +} + +impl FromStr for DocumentationLength { + type Err = String; + + fn from_str(s: &str) -> Result { + match s.to_lowercase().as_ref() { + "short" => Ok(DocumentationLength::Short), + "full" => Ok(DocumentationLength::Full), + _ => Err(format!("Unrecognized documentation style: '{}'.", s)), + } + } +} + +deserialize_enum_str!(DocumentationLength); + /// A style of Style to use when generating structs and enums. #[derive(Debug, Copy, Clone, PartialEq)] pub enum Style { @@ -935,6 +956,8 @@ pub struct Config { pub documentation: bool, /// How documentation comments should be styled. pub documentation_style: DocumentationStyle, + /// How much of the documentation should be output for each item. + pub documentation_length: DocumentationLength, /// Configuration options for pointers #[serde(rename = "ptr")] pub pointer: PtrConfig, @@ -1013,6 +1036,7 @@ impl Default for Config { defines: HashMap::new(), documentation: true, documentation_style: DocumentationStyle::Auto, + documentation_length: DocumentationLength::Full, pointer: PtrConfig::default(), only_target_dependencies: false, cython: CythonConfig::default(), diff --git a/src/bindgen/ir/documentation.rs b/src/bindgen/ir/documentation.rs index f08440c51..8d5fcb6cb 100644 --- a/src/bindgen/ir/documentation.rs +++ b/src/bindgen/ir/documentation.rs @@ -4,7 +4,7 @@ use std::io::Write; -use crate::bindgen::config::{Config, DocumentationStyle, Language}; +use crate::bindgen::config::{Config, DocumentationLength, DocumentationStyle, Language}; use crate::bindgen::utilities::SynAttributeHelpers; use crate::bindgen::writer::{Source, SourceWriter}; @@ -76,7 +76,12 @@ impl Source for Documentation { _ => (), } - for line in &self.doc_comment { + let end = match config.documentation_length { + DocumentationLength::Short => 1, + DocumentationLength::Full => self.doc_comment.len(), + }; + + for line in &self.doc_comment[..end] { match style { DocumentationStyle::C => out.write(""), DocumentationStyle::Doxy => out.write(" *"), diff --git a/template.toml b/template.toml index 95669ad62..bc414290e 100644 --- a/template.toml +++ b/template.toml @@ -36,6 +36,7 @@ line_length = 100 tab_width = 2 documentation = true documentation_style = "auto" +documentation_length = "full" line_endings = "LF" # also "CR", "CRLF", "Native" diff --git a/tests/expectations/doclength_short.c b/tests/expectations/doclength_short.c new file mode 100644 index 000000000..f08e6e3c3 --- /dev/null +++ b/tests/expectations/doclength_short.c @@ -0,0 +1,14 @@ +#include +#include +#include +#include + +/** + * The root of all evil. + */ +void root(void); + +/** + * A little above the root, and a lot more visible, with a run-on sentence + */ +void trunk(void); diff --git a/tests/expectations/doclength_short.compat.c b/tests/expectations/doclength_short.compat.c new file mode 100644 index 000000000..c871ab292 --- /dev/null +++ b/tests/expectations/doclength_short.compat.c @@ -0,0 +1,22 @@ +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif // __cplusplus + +/** + * The root of all evil. + */ +void root(void); + +/** + * A little above the root, and a lot more visible, with a run-on sentence + */ +void trunk(void); + +#ifdef __cplusplus +} // extern "C" +#endif // __cplusplus diff --git a/tests/expectations/doclength_short.cpp b/tests/expectations/doclength_short.cpp new file mode 100644 index 000000000..162a0503b --- /dev/null +++ b/tests/expectations/doclength_short.cpp @@ -0,0 +1,15 @@ +#include +#include +#include +#include +#include + +extern "C" { + +/// The root of all evil. +void root(); + +/// A little above the root, and a lot more visible, with a run-on sentence +void trunk(); + +} // extern "C" diff --git a/tests/expectations/doclength_short.pyx b/tests/expectations/doclength_short.pyx new file mode 100644 index 000000000..72bf95655 --- /dev/null +++ b/tests/expectations/doclength_short.pyx @@ -0,0 +1,20 @@ +from libc.stdint cimport int8_t, int16_t, int32_t, int64_t, intptr_t +from libc.stdint cimport uint8_t, uint16_t, uint32_t, uint64_t, uintptr_t +cdef extern from *: + ctypedef bint bool + ctypedef struct va_list + +cdef extern from *: + + # The root of all evil. + # + # But at least it contains some more documentation as someone would expect + # from a simple test case like this. Though, this shouldn't appear in the + # output. + void root(); + + # A little above the root, and a lot more visible, with a run-on sentence + # to test going over the first line. + # + # Still not here, though. + void trunk(); diff --git a/tests/rust/doclength_short.rs b/tests/rust/doclength_short.rs new file mode 100644 index 000000000..363a24553 --- /dev/null +++ b/tests/rust/doclength_short.rs @@ -0,0 +1,16 @@ +/// The root of all evil. +/// +/// But at least it contains some more documentation as someone would expect +/// from a simple test case like this. Though, this shouldn't appear in the +/// output. +#[no_mangle] +pub extern "C" fn root() { +} + +/// A little above the root, and a lot more visible, with a run-on sentence +/// to test going over the first line. +/// +/// Still not here, though. +#[no_mangle] +pub extern "C" fn trunk() { +} diff --git a/tests/rust/doclength_short.toml b/tests/rust/doclength_short.toml new file mode 100644 index 000000000..30a7d79f6 --- /dev/null +++ b/tests/rust/doclength_short.toml @@ -0,0 +1 @@ +documentation_length = "short" diff --git a/tests/tests.rs b/tests/tests.rs index 81c43e3d6..3b44eac3c 100644 --- a/tests/tests.rs +++ b/tests/tests.rs @@ -208,6 +208,10 @@ fn run_compile_test( cbindgen_outputs.insert(cbindgen_output); + if env::var_os("CBINDGEN_TEST_NO_COMPILE").is_some() { + return; + } + compile( &generated_file, &tests_path,