code review 7407050: cmd/cgo: add implementation comment

cmd/cgo: add implementation comment

[rsc, 2013-02-27 19:10:58]

Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://go.googlecode.com/hg

[r, 2013-02-27 19:23:21]

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go
File src/cmd/cgo/doc.go (right):

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go#newcode145
src/cmd/cgo/doc.go:145: import "C". If the import has an attached doc comment,
that comment is
"attached doc comment": i know what you mean but it's novel phrasing. anyway if
it's not attached it's not a doc comment.

maybe

If the import has a doc comment, that is, an immediately preceding comment
suitable for godoc, that comment...

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go#newcode146
src/cmd/cgo/doc.go:146: taken as literal C code to be used as a preamble to any
C code
again, what does preamble mean? and how does cgo compile c?
perhaps you need a general overview introducing the terms and flow, followed by
the detailed description. you see the big picture already but the reader (me)
does not.

maybe after your first sentence, another sentence or two explaining the flow

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go#newcode249
src/cmd/cgo/doc.go:249: files:
on amd64-darwin? linux? does it matter?

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go#newcode260
src/cmd/cgo/doc.go:260: The file x.cgo1.go is a copy x.go with the import "C"
removed and
s/copy/copy of/

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go#newcode367
src/cmd/cgo/doc.go:367: The main benefits of this system are that it is simple
and that gcc is
simple? simpler than other approaches perhaps, but not simple. it is very clever

[bradfitz, 2013-02-27 19:27:10]

LGTM

Wow, nice. That's crazier than I thought.

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go
File src/cmd/cgo/doc.go (right):

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go#newcode169
src/cmd/cgo/doc.go:169: identifiers not by parsing C code but by feeding
carefully constructed
carefully-constructed ?

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go#newcode283
src/cmd/cgo/doc.go:283: Go runtime world to the system C (gcc) world.
gcc?

[rsc, 2013-02-27 19:31:48]

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go
File src/cmd/cgo/doc.go (right):

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go#newcode146
src/cmd/cgo/doc.go:146: taken as literal C code to be used as a preamble to any
C code
I think the doc comment at the top of the file covers most of this.

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go#newcode283
src/cmd/cgo/doc.go:283: Go runtime world to the system C (gcc) world.
On 2013/02/27 19:27:10, bradfitz wrote:
> gcc?

Not sure what the question is.

[rsc, 2013-02-27 19:37:45]

Hello golang-dev@googlegroups.com, r@golang.org, bradfitz@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[r, 2013-02-27 19:44:32]

LGTM but ask iant about gcc vs GCC

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go
File src/cmd/cgo/doc.go (right):

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go#newcode283
src/cmd/cgo/doc.go:283: Go runtime world to the system C (gcc) world.
i bet it's that "system C (gcc)" is inscrutable.  

world of the Go runtime to that of the C runtime as implemented by gcc.

or maybe just

the Go world to the C world as implemented by gcc.

by the way, is it gcc or GCC?

https://codereview.appspot.com/7407050/diff/9001/src/cmd/cgo/doc.go
File src/cmd/cgo/doc.go (right):

https://codereview.appspot.com/7407050/diff/9001/src/cmd/cgo/doc.go#newcode172
src/cmd/cgo/doc.go:172: identifiers not by parsing C code but by feeding
carefully constructed
all programs are carefully constructed, or should be.
how about "exploratory"

https://codereview.appspot.com/7407050/diff/9001/src/cmd/cgo/doc.go#newcode175
src/cmd/cgo/doc.go:175: parsing these is significantly less work and more robust
than parsing
s/these/& outputs from the compiler

[iant, 2013-02-27 21:20:51]

LGTM

Seems like some of this may change when we start using the host linker.

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go
File src/cmd/cgo/doc.go (right):

https://codereview.appspot.com/7407050/diff/2001/src/cmd/cgo/doc.go#newcode283
src/cmd/cgo/doc.go:283: Go runtime world to the system C (gcc) world.
On 2013/02/27 19:44:32, r wrote:
> 
> by the way, is it gcc or GCC?

It's usually GCC.

https://codereview.appspot.com/7407050/diff/9001/src/cmd/cgo/doc.go
File src/cmd/cgo/doc.go (right):

https://codereview.appspot.com/7407050/diff/9001/src/cmd/cgo/doc.go#newcode289
src/cmd/cgo/doc.go:289: similar bodies that invoke runtime.cgocall to make a
switch from the
s/./·/ ?

[rsc, 2013-02-28 04:52:14]

On Wed, Feb 27, 2013 at 4:20 PM, <iant@golang.org> wrote:

> Seems like some of this may change when we start using the host linker.


In many cases I am referring to the command, not the compiler collection /
toolchain.
I will change the references to the toolchain to GCC.

Russ

[rsc, 2013-02-28 04:55:06]

*** Submitted as https://code.google.com/p/go/source/detail?r=62bf913b4f40 ***

cmd/cgo: add implementation comment

R=golang-dev, r, bradfitz, iant
CC=golang-dev
https://codereview.appspot.com/7407050