From 983ccf83690d777bda71e4d93703c5227f94457d Mon Sep 17 00:00:00 2001
From: David Tolnay <dtolnay@gmail.com>
Date: Thu, 8 Oct 2020 17:03:35 -0700
Subject: [PATCH] Add documentation on CFG and Cfg

---
 gen/build/src/cfg.rs | 53 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/gen/build/src/cfg.rs b/gen/build/src/cfg.rs
index ecc9bfb78..05578dfe2 100644
--- a/gen/build/src/cfg.rs
+++ b/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: "",