From 5ac186975c8a792a4504060001df12fa3ba2ba4e Mon Sep 17 00:00:00 2001
From: Ian Lance Taylor <iant@golang.org>
Date: Thu, 22 Mar 2012 17:44:28 -0700
Subject: [PATCH] doc/articles/c_go_cgo.html: correct "C" comment to mention
 #cgo

Also fix invalid apostrophe characters.

R=r, gri, adg
CC=golang-dev
https://golang.org/cl/5874058
---
 doc/articles/c_go_cgo.html | 44 +++++++++++++++++++++++++++-----------
 1 file changed, 32 insertions(+), 12 deletions(-)

diff --git a/doc/articles/c_go_cgo.html b/doc/articles/c_go_cgo.html
index 1709f06d2a..ac6bb29a2f 100644
--- a/doc/articles/c_go_cgo.html
+++ b/doc/articles/c_go_cgo.html
@@ -18,7 +18,7 @@ and <code>srandom</code> functions.
 {{code "/doc/progs/cgo1.go" `/package rand/` `/END/`}}
 
 <p>
-Let’s look at what's happening here, starting with the import statement.
+Let's look at what's happening here, starting with the import statement.
 </p>
 
 <p>
@@ -45,7 +45,7 @@ package, using an ordinary Go type conversion:
 {{code "/doc/progs/cgo1.go" `/func Random/` `/STOP/`}}
 
 <p>
-Here’s an equivalent function that uses a temporary variable to illustrate
+Here's an equivalent function that uses a temporary variable to illustrate
 the type conversion more explicitly:
 </p>
 
@@ -73,11 +73,31 @@ above the <code>import</code> statement.
 {{code "/doc/progs/cgo1.go" `/\/\*/` `/STOP/`}}
 
 <p>
-Cgo recognizes this comment and uses it as a header when compiling the C
-parts of the package. In this case it is just a simple include statement,
-but it can be any valid C code. The comment must be immediately before the
-line that imports <code>"C"</code>, without any intervening blank lines,
-just like a documentation comment.
+Cgo recognizes this comment.  Any lines starting
+with <code>#cgo</code>
+followed
+by a space character are removed; these become directives for cgo.
+The remaining lines are used as a header when compiling the C parts of
+the package.  In this case those lines are just a
+single <code>#include</code>
+statement, but they can be almost any C code.  The <code>#cgo</code>
+directives are
+used to provide flags for the compiler and linker when building the C
+parts of the package.
+</p>
+
+<p>
+There is a limitation: if your program uses any <code>//export</code>
+directives, then the C code in the comment may only include declarations
+(<code>extern int f();</code>), not definitions (<code>int f() {
+return 1; }</code>).  You can use <code>//export</code> directives to
+make Go functions accessible to C code.
+</p>
+
+<p>
+The <code>#cgo</code> and <code>//export</code> directives are
+documented in
+the <a href="/cmd/cgo/">cgo documentation</a>.
 </p>
 
 <p>
@@ -85,7 +105,7 @@ just like a documentation comment.
 </p>
 
 <p>
-Unlike Go, C doesn’t have an explicit string type. Strings in C are
+Unlike Go, C doesn't have an explicit string type. Strings in C are
 represented by a zero-terminated array of chars.
 </p>
 
@@ -107,7 +127,7 @@ string to standard output using C's <code>fputs</code> function from the
 <p>
 Memory allocations made by C code are not known to Go's memory manager.
 When you create a C string with <code>C.CString</code> (or any C memory
-allocation) you must remember to free the memory when you’re done with it
+allocation) you must remember to free the memory when you're done with it
 by calling <code>C.free</code>.
 </p>
 
@@ -147,7 +167,7 @@ in the Go tree demonstrate more advanced concepts.
 </p>
 
 <p>
-For a simple, idiomatic example of a cgo-based package, see Russ Cox’s <a
+For a simple, idiomatic example of a cgo-based package, see Russ Cox's <a
 href="http://code.google.com/p/gosqlite/source/browse/sqlite/sqlite.go">gosqlite</a>.
 Also, the Go Project Dashboard lists <a
 href="https://godashboard.appspot.com/project?tag=cgo">several other
@@ -155,6 +175,6 @@ cgo packages</a>.
 </p>
 
 <p>
-Finally, if you’re curious as to how all this works internally, take a look
-at the introductory comment of the runtime package’s <a href="/src/pkg/runtime/cgocall.c">cgocall.c</a>.
+Finally, if you're curious as to how all this works internally, take a look
+at the introductory comment of the runtime package's <a href="/src/pkg/runtime/cgocall.c">cgocall.c</a>.
 </p>