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 <[email protected]>

Author: randall77

doc/go1.10.html

@@ -262,8 +262,6 @@ <h3 id="cgo">Cgo</h3>
 
 <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 @@ <h3 id="cgo">Cgo</h3>
 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>

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.