let's try to wrap this up

libcsp-cargo-build/src/lib.rs

@@ -1,3 +1,6 @@
+//! This crate provides a library to allow building the [`libcsp`](https://github.com/libcsp/libcsp)
+//! C library with cargo. You can find some more high-level information and examples in the
+//! [main repository](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust).
 use std::{
     io::{self, Write},
     path::{Path, PathBuf},
@@ -109,6 +112,17 @@ impl Default for Config {
     }
 }
 
+/// Primary builder structure used to compile the `libcsp` C library.
+///
+/// The [Self::cfg] field can be used to configure the library build. The will also take care
+/// of generating the autoconfig.h file required for the library configuration automatically based
+/// on the build [Config]. An API is also provided to generate the autoconfig.rs file required
+/// for compiling the [`libcsp-sys`](https://crates.io/crates/libcp-sys) Rust FFI bindings crate.
+///
+/// ## Example
+///
+/// The [example buildscript](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust/src/branch/main/examples/build.rs)
+/// uses this builder structure to compile the library.
 pub struct Builder {
     generate_autoconf_file: bool,
     libcsp_path: PathBuf,
@@ -120,6 +134,7 @@ pub struct Builder {
 }
 
 impl Builder {
+    /// Create a new builder instance.
     pub fn new(libcsp_path: PathBuf, out_dir: PathBuf) -> Self {
         let mut libcsp_src_path_base = libcsp_path.clone();
         libcsp_src_path_base.push("src");
@@ -134,7 +149,13 @@ impl Builder {
         }
     }
 
-    pub fn cc(&mut self) -> &mut cc::Build {
+    /// Access to the underlying [cc::Build] builder object.
+    pub fn cc(&mut self) -> &cc::Build {
+        &self.build
+    }
+
+    /// Mutable access to the underlying [cc::Build] builder object.
+    pub fn cc_mut(&mut self) -> &mut cc::Build {
         &mut self.build
     }
 
@@ -187,6 +208,8 @@ impl Builder {
         self.build.cargo_warnings(self.compiler_warnings);
 
         self.build.compile("csp");
+        // TODO: We could generate some sort of information file which contains the
+        // compilation information and the version of hte library.
         Ok(())
     }
 
@@ -216,13 +239,21 @@ impl Builder {
     }
 }
 
+/// Generate the autoconfig.h file which is required to build the C library. This file contains
+/// important configuration defines.
 pub fn generate_autoconf_header_file(out_dir: impl AsRef<Path>, cfg: &Config) -> io::Result<()> {
     let out_dir = out_dir.as_ref();
     let mut autoconf_file_string = String::new();
-    autoconf_file_string
-        .push_str("// This file was auto-generated by the libcsp-cargo-build library\n");
+    let version = env!("CARGO_PKG_VERSION");
+    let name = env!("CARGO_PKG_NAME");
+    autoconf_file_string.push_str(&format!(
+        "// This file was auto-generated by {} v{}\n",
+        name, version
+    ));
     #[cfg(unix)]
     autoconf_file_string.push_str("#define CSP_POSIX 1\n");
+    #[cfg(not(unix))]
+    autoconf_file_string.push_str("#define CSP_POSIX 0\n");
     autoconf_file_string.push_str("#define CSP_ZEPHYR 0\n");
     autoconf_file_string.push('\n');
     autoconf_file_string.push_str(&format!(
@@ -320,11 +351,17 @@ pub fn generate_autoconf_header_file(out_dir: impl AsRef<Path>, cfg: &Config) ->
     Ok(())
 }
 
+/// Generate the autoconfig.rs file which is required by the
+/// [`libcsp-sys`](https://crates.io/crates/libcsp-sys) Rust bindings crate.
 pub fn generate_autoconf_rust_file(out_dir: impl AsRef<Path>, cfg: &Config) -> io::Result<()> {
     let out_dir = out_dir.as_ref();
     let mut autoconf_file_string = String::new();
-    autoconf_file_string
-        .push_str("// This file was auto-generated by the libcsp-cargo-build library\n");
+    let version = env!("CARGO_PKG_VERSION");
+    let name = env!("CARGO_PKG_NAME");
+    autoconf_file_string.push_str(&format!(
+        "// This file was auto-generated by {} v{}\n",
+        name, version
+    ));
     autoconf_file_string.push_str(&format!(
         "pub const {}: usize = {};\n",
         cfg_keys::CONN_RXQUEUE_LEN,