Add documentation_style to with short and full options

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"
+
 
 
 

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<DocumentationLength, Self::Err> {
+        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(),

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(" *"),

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"
 
 

tests/expectations/doclength_short.c

@@ -0,0 +1,14 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+/**
+ * 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);

tests/expectations/doclength_short.compat.c

@@ -0,0 +1,22 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#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

tests/expectations/doclength_short.cpp

@@ -0,0 +1,15 @@
+#include <cstdarg>
+#include <cstdint>
+#include <cstdlib>
+#include <ostream>
+#include <new>
+
+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"

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();

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() {
+}

tests/rust/doclength_short.toml

@@ -0,0 +1 @@
+documentation_length = "short"

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,