runtime/cgo: clarify Handle documentation

Fixes #45427

Change-Id: Ic67630a5f39d8789a4a30c6b4ee30946bc50382e
Reviewed-on: https://go-review.googlesource.com/c/go/+/308230
Trust: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Ainar Garipov <gugl.zadolbal@gmail.com>
Reviewed-by: Changkun Ou <euryugasaki@gmail.com>
Reviewed-by: Emmanuel Odeke <emmanuel@orijtech.com>

src/runtime/cgo/handle.go

@@ -9,12 +9,18 @@ import (
 	"sync/atomic"
 )
 
-// Handle provides a safe representation of Go values to pass between
+// Handle provides a way to pass values that contain Go pointers
-// Go and C. The zero value of a handle is not a valid handle, and thus
+// (pointers to memory allocated by Go) between Go and C without
-// is safe to use as a sentinel in C APIs.
+// breaking the cgo pointer passing rules. A Handle is an integer
+// value that can represent any Go value. A Handle can be passed
+// through C and back to Go, and Go code can use the Handle to
+// retrieve the original Go value.
 //
 // The underlying type of Handle is guaranteed to fit in an integer type
-// that is large enough to hold the bit pattern of any pointer.
+// that is large enough to hold the bit pattern of any pointer. The zero
+// value of a Handle is not valid, and thus is safe to use as a sentinel
+// in C APIs.
+//
 // For instance, on the Go side:
 //
 //	package main
@@ -31,15 +37,15 @@ import (
 //	//export MyGoPrint
 //	func MyGoPrint(handle C.uintptr_t) {
 //		h := cgo.Handle(handle)
-// 		val := h.Value().(int)
+//		val := h.Value().(string)
 //		println(val)
 //		h.Delete()
 //	}
 //
 //	func main() {
-// 		val := 42
+//		val := "hello Go"
 //		C.myprint(C.uintptr_t(cgo.NewHandle(val)))
-// 		// Output: 42
+//		// Output: hello Go
 //	}
 //
 // and on the C side: