Add documentation on CFG and Cfg

gen/build/src/cfg.rs

@@ -1,11 +1,64 @@
 use std::fmt::{self, Debug};
 use std::marker::PhantomData;
 
+/// Build configuration. See [CFG].
 pub struct Cfg<'a> {
     pub include_prefix: &'a str,
     marker: PhantomData<*const ()>, // !Send + !Sync
 }
 
+/// Global configuration of the current build.
+///
+/// <br>
+///
+/// ## **`CFG.include_prefix`**
+///
+/// Presently the only exposed configuration is the `include_prefix`, the prefix
+/// at which C++ code from your crate as well as directly dependent crates can
+/// access the code generated during this build.
+///
+/// By default, the `include_prefix` is equal to the name of the current crate.
+/// That means if our crate is called `demo` and has Rust source files in a
+/// *src/* directory and maybe some handwritten C++ header files in an
+/// *include/* directory, then the current crate as well as downstream crates
+/// might include them as follows:
+///
+/// ```
+/// # const _: &str = stringify! {
+///   // include one of the handwritten headers:
+/// #include "demo/include/wow.h"
+///
+///   // include a header generated from Rust cxx::bridge:
+/// #include "demo/src/lib.rs.h"
+/// # };
+/// ```
+///
+/// By modifying `CFG.include_prefix` we can substitute a prefix that is
+/// different from the crate name if desired. Here we'll change it to
+/// `"path/to"` which will make import paths take the form
+/// `"path/to/include/wow.h"` and `"path/to/src/lib.rs.h"`.
+///
+/// ```no_run
+/// // build.rs
+///
+/// use cxx_build::CFG;
+///
+/// fn main() {
+///     CFG.include_prefix = "path/to";
+///
+///     cxx_build::bridge("src/lib.rs")
+///         .file("src/demo.cc") // probably contains `#include "path/to/src/lib.rs.h"`
+///         /* ... */
+///         .compile("demo");
+/// }
+/// ```
+///
+/// Note that cross-crate imports are only made available between **direct
+/// dependencies**. Another crate must directly depend on your crate in order to
+/// #include its headers; a transitive dependency is not sufficient.
+/// Additionally, headers from a direct dependency are only importable if the
+/// dependency's Cargo.toml manifest contains a `links` key. If not, its headers
+/// will not be importable from outside of the same crate.
 #[cfg(doc)]
 pub static mut CFG: Cfg = Cfg {
     include_prefix: "",