From 25363de2266a3b53204065637eb509a8cc4d72c3 Mon Sep 17 00:00:00 2001
From: Keith Randall <khr@golang.org>
Date: Fri, 8 Dec 2017 08:38:15 -0800
Subject: [PATCH] doc: add doc about C types that we map to uintptr instead of
 ptr

Update #22906
Update #21897

Change-Id: I73709b2fdac6981d4bc2f7dab0767f2dd7be3be5
Reviewed-on: https://go-review.googlesource.com/82917
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
---
 doc/go1.10.html    | 27 +++++++++++++++++++++++++--
 src/cmd/cgo/doc.go | 23 +++++++++++++++++++++--
 2 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/doc/go1.10.html b/doc/go1.10.html
index 1644f3cdb2..f2b57e32f9 100644
--- a/doc/go1.10.html
+++ b/doc/go1.10.html
@@ -262,8 +262,6 @@ Go structs and Go arrays are not supported in the type signatures of cgo-exporte
 
 <p>
 TODO: CL 70890 "permit passing string values directly between Go and C."
-<br>
-TODO: CL 66332 "special case C ptr types to use uintptr."
 </p>
 
 <p>
@@ -279,6 +277,31 @@ Later <code>go</code> <code>build</code> commands refer to the <code>CC</code> e
 variable or else the built-in default.
 </p>
 
+<p>
+Cgo now translates some C types that would normally map to a pointer
+type in Go, to a <code>uintptr</code> instead. These types include
+the <code>CFTypeRef</code> hierarchy in Darwin's CoreFoundation
+framework and the <code>jobject</code> hierarchy in Java's JNI
+interface.
+</p>
+
+<p>
+These types must be <code>uintptr</code> on the Go side because they
+would otherwise confuse the Go garbage collector; they are sometimes
+not really pointers but data structures encoded in a pointer type.
+</p>
+
+<p>
+Because of this change, values of the affected types need to be
+zero-initialized with the constant <code>0</code> instead of the
+constant <code>nil</code>. Go 1.10 provides <code>gofix</code>
+modules to help with that rewrite:
+<pre>
+	go tool fix -r cftype <pkg>
+	go tool fix -r jni <pkg>
+</pre>
+</p>
+
 <p>
 For more details, see the <a href="/cmd/cgo/">cgo documentation</a>.
 </p>
diff --git a/src/cmd/cgo/doc.go b/src/cmd/cgo/doc.go
index c1bdf0659f..0b64b31d46 100644
--- a/src/cmd/cgo/doc.go
+++ b/src/cmd/cgo/doc.go
@@ -403,16 +403,35 @@ the CF*Ref types from the CoreFoundation library on Darwin, including:
 	CFXMLParserRef
 	CFXMLTreeRef
 
+Also the object types from Java's JNI interface:
+
+	jobject
+	jclass
+	jthrowable
+	jstring
+	jarray
+	jbooleanArray
+	jbyteArray
+	jcharArray
+	jshortArray
+	jintArray
+	jlongArray
+	jfloatArray
+	jdoubleArray
+	jobjectArray
+	jweak
+
 These types are uintptr on the Go side because they would otherwise
 confuse the Go garbage collector; they are sometimes not really
 pointers but data structures encoded in a pointer type. All operations
 on these types must happen in C. The proper constant to initialize an
 empty such reference is 0, not nil.
 
-This special case was introduced in Go 1.10. For auto-updating code
-from Go 1.9 and earlier, use the cftype rewrite in the Go fix tool:
+These special cases were introduced in Go 1.10. For auto-updating code
+from Go 1.9 and earlier, use the cftype or jni rewrites in the Go fix tool:
 
 	go tool fix -r cftype <pkg>
+	go tool fix -r jni <pkg>
 
 It will replace nil with 0 in the appropriate places.
 
-- 
2.50.0