From 2b564aeb06328ee23712cf7aabece889f0f8a01b Mon Sep 17 00:00:00 2001
From: John Doneth <doneth7@gmail.com>
Date: Fri, 4 Oct 2019 11:26:53 -0400
Subject: [PATCH] chore(docs): Add documentation for modified tonic-build
 output directory (#40)

* improve docs for modified OUT_DIR

* rustfmt
---
 tonic/src/macros.rs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/tonic/src/macros.rs b/tonic/src/macros.rs
index beb0c3b..828e70e 100644
--- a/tonic/src/macros.rs
+++ b/tonic/src/macros.rs
@@ -7,6 +7,26 @@
 ///     tonic::include_proto("helloworld");
 /// }
 /// ```
+///
+/// # Note:
+/// **This only works if the tonic-build output directory has been unmodified**.
+/// The default output directory is set to the [`OUT_DIR`] environment variable.
+/// If the output directory has been modified, the following pattern may be used
+/// instead of this macro.
+///
+/// ```rust,ignore
+/// mod pb {
+///     include!("/relative/protobuf/directory/helloworld.rs");
+/// }
+/// ```
+/// You can also use a custom environment variable using the following pattern.
+/// ```rust,ignore
+/// mod pb {
+///     include!(concat!(env!("PROTOBUFS"), concat!("/helloworld.rs")));
+/// }
+/// ```
+///
+/// [`OUT_DIR`]: https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts
 #[macro_export]
 macro_rules! include_proto {
     ($package: tt) => {