From 3a11757d575342be0623dd5ec50f3a8aa10a3098 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <superjoe30@gmail.com>
Date: Wed, 31 Jan 2018 20:18:47 -0500
Subject: [PATCH] add docs recommending to only have 1 cImport

---
 doc/langref.html.in | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 986da22dd2f5bd3b0a64e90e2492a41d4ad6079d..6321dddff792d11c5f1c00d96e2fa13ba3d8e6e8 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -3887,6 +3887,17 @@ comptime {
       <code>@cInclude</code>, <code>@cDefine</code>, and <code>@cUndef</code> work
       within this expression, appending to a temporary buffer which is then parsed as C code.
       </p>
+      <p>
+      Usually you should only have one <code>@cImport</code> in your entire application, because it saves the compiler
+      from invoking clang multiple times, and prevents inline functions from being duplicated.
+      </p>
+      <p>
+      Reasons for having multiple <code>@cImport</code> expressions would be:
+      </p>
+      <ul>
+        <li>To avoid a symbol collision, for example if foo.h and bar.h both <code>#define CONNECTION_COUNT</code></li>
+        <li>To analyze the C code with different preprocessor defines</li>
+      </ul>
       {#see_also|Import from C Header File|@cInclude|@cDefine|@cUndef#}
       {#header_close#}
       {#header_open|@cInclude#}
-- 
2.54.0