runtime/cgo: document Handle better

[ainar-g]

CL 295369 (issue #37033) added the new type runtime/cgo.Handle. The documentation currently says:

Handle provides a safe representation of Go values to pass between Go and C. The zero value of a handle is not a valid handle, and thus is safe to use as a sentinel in C APIs.

But it doesn't mention what it means by an “unsafe” value. I assume that what it means is a reference to the “Passing pointers” section of the cgo documentation, but the example code that the package currently provides simply passes a [pointer to an] integer between Go and C.

I think that the code should be replaced with something better documented and closer to real-world scenarios, and also that perhaps direct links to the cgo documentation about which values are typically unsafe should be added.

[dmitshur]

CC @oakad, @changkun, @ianlancetaylor.

[ianlancetaylor]

@ainar-g Please comment on https://golang.org/cl/308230. Thanks.

[gopherbot]

Change https://golang.org/cl/308230 mentions this issue: runtime/cgo: clarify Handle documentation