improve doc comment for generated_code macro

Author: dwrensha

capnp/src/lib.rs

@@ -64,11 +64,22 @@ pub mod text;
 pub mod text_list;
 pub mod traits;
 
-/// Macro for importing a Rust file generated by a `build.rs` file using
-/// `capnpc::CompilerCommand`.
+/// Macro for importing Rust code that has been generated by `capnpc::CompilerCommand`.
 ///
-/// Typically, a schema file named `foo.capnp` should have a `mod_name`
-/// of `foo_capnp` and a `file_name` of `"foo_capnp.rs"`.
+/// For example:
+/// ```ignore
+/// generated_code!(pub mod foo_capnp);
+/// ```
+/// pulls in the generated code for `foo.capnp` into a module named `foo_capnp`.
+/// It expects to find the generated code in a file `$OUT_DIR/foo_capnp.rs`,
+/// where `OUT_DIR` is Cargo's standard environment variable giving the
+/// location of the output of `build.rs`.
+///
+/// If the generated code lives in a nonstandard location—perhaps in a subdirectory
+/// of `OUT_DIR`—you can specify its path as a second argument:
+/// ```ignore
+/// generated_code!(pub mod foo_capnp, "some_directory/foo_capnp.rs");
+/// ```
 #[macro_export]
 macro_rules! generated_code {
     ($vis:vis mod $mod_name:ident, $file_name:expr) => {