From d05b3869286a48afbc228992b314f0bf817afc48 Mon Sep 17 00:00:00 2001 From: Shenghou Ma Date: Mon, 19 Mar 2012 22:54:06 +0800 Subject: [PATCH] doc: update format for "C? Go? Cgo!" article R=adg CC=golang-dev https://golang.org/cl/5841050 --- doc/articles/c_go_cgo.html | 59 +++++++++++++++++++------------------- doc/progs/cgo1.go | 2 -- 2 files changed, 30 insertions(+), 31 deletions(-) diff --git a/doc/articles/c_go_cgo.html b/doc/articles/c_go_cgo.html index 5244021972..1709f06d2a 100644 --- a/doc/articles/c_go_cgo.html +++ b/doc/articles/c_go_cgo.html @@ -22,24 +22,24 @@ Let’s look at what's happening here, starting with the import statement.

-The rand package imports "C", but you'll find there's no such package in -the standard Go library. That's because C is a +The rand package imports "C", but you'll find there's +no such package in the standard Go library. That's because C is a "pseudo-package", a special name interpreted by cgo as a reference to C's name space.

-The rand package contains four references to the C package: -the calls to C.random and C.srandom, the -conversion C.uint(i), and the import statement. +The rand package contains four references to the C +package: the calls to C.random and C.srandom, the +conversion C.uint(i), and the import statement.

-The Random function calls the libc random function and returns -the result. In C, random returns a value of the C type long, -which cgo represents as the type C.long. It must be converted -to a Go type before it can be used by Go code outside this package, using -an ordinary Go type conversion: +The Random function calls the standard C library's random +function and returns the result. In C, random returns a value of the +C type long, which cgo represents as the type C.long. +It must be converted to a Go type before it can be used by Go code outside this +package, using an ordinary Go type conversion:

{{code "/doc/progs/cgo1.go" `/func Random/` `/STOP/`}} @@ -54,30 +54,30 @@ the type conversion more explicitly:

The Seed function does the reverse, in a way. It takes a regular Go int, converts it to the C unsigned int -type, and passes it to the C function srandom. +type, and passes it to the C function srandom.

{{code "/doc/progs/cgo1.go" `/func Seed/` `/END/`}}

-Note that cgo knows the unsigned int type as C.uint; see the -cgo documentation for a complete list of these -numeric type names. +Note that cgo knows the unsigned int type as C.uint; +see the cgo documentation for a complete list of +these numeric type names.

The one detail of this example we haven't examined yet is the comment -above the import statement. +above the import statement.

-{{code "/doc/progs/cgo1.go" `/INCLUDE/` `/STOP/`}} +{{code "/doc/progs/cgo1.go" `/\/\*/` `/STOP/`}}

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 "C", without any intervening blank lines, just like a -documentation comment. +line that imports "C", without any intervening blank lines, +just like a documentation comment.

@@ -114,11 +114,11 @@ by calling C.free.

The call to C.CString returns a pointer to the start of the char array, so before the function exits we convert it to an -unsafe.Pointer and release the memory -allocation with C.free. A common idiom in cgo programs is to -defer the free -immediately after allocating (especially when the code that follows is more -complex than a single function call), as in this rewrite of +unsafe.Pointer and release +the memory allocation with C.free. A common idiom in cgo programs +is to defer +the free immediately after allocating (especially when the code that follows +is more complex than a single function call), as in this rewrite of Print:

@@ -129,10 +129,11 @@ complex than a single function call), as in this rewrite of

-To build cgo packages, just use "go build" or -"go install" -as usual. The go tool recognizes the special "C" import and automatically uses -cgo for those files. +To build cgo packages, just use " +go build" or +"go install +" as usual. The go tool recognizes the special "C" import and automatically +uses cgo for those files.

@@ -141,8 +142,8 @@ cgo for those files.

The cgo command documentation has more detail about -the C pseudo-package and the build process. The cgo examples in the Go tree -demonstrate more advanced concepts. +the C pseudo-package and the build process. The cgo examples +in the Go tree demonstrate more advanced concepts.

diff --git a/doc/progs/cgo1.go b/doc/progs/cgo1.go index 3125cda3d8..b79ee368a4 100644 --- a/doc/progs/cgo1.go +++ b/doc/progs/cgo1.go @@ -3,8 +3,6 @@ // license that can be found in the LICENSE file. package rand -// INCLUDE OMIT - /* #include */ -- 2.52.0