From 8b0b994c08c540702fbfe84a50ed72b93892d7c5 Mon Sep 17 00:00:00 2001
From: Rob Pike <r@golang.org>
Date: Tue, 18 Feb 2014 22:33:59 -0800
Subject: [PATCH] reflect: improve documentation of IsNil IsNil isn't quite the
 same as == nil, as this snippet shows:

// http://play.golang.org/p/huomslDZgw
package main

import "fmt"
import "reflect"

func main() {
        var i interface{}
        v := reflect.ValueOf(i)
        fmt.Println(v.IsValid(), i == nil)
        fmt.Println(v.IsNil())
}

The fact that IsNil panics if you call it with an untyped nil
was not apparent. Verbiage added for clarity.

LGTM=rsc
R=rsc
CC=golang-codereviews
https://golang.org/cl/65480043
---
 src/pkg/reflect/value.go | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/pkg/reflect/value.go b/src/pkg/reflect/value.go
index 2490f6d13b..1edb1f0465 100644
--- a/src/pkg/reflect/value.go
+++ b/src/pkg/reflect/value.go
@@ -1091,8 +1091,13 @@ func (v Value) InterfaceData() [2]uintptr {
 	return *(*[2]uintptr)(v.ptr)
 }
 
-// IsNil returns true if v is a nil value.
-// It panics if v's Kind is not Chan, Func, Interface, Map, Ptr, or Slice.
+// IsNil reports whether its argument v is nil. The argument must be
+// a chan, func, interface, map, pointer, or slice value; if it is
+// not, IsNil panics. Note that IsNil is not always equivalent to a
+// regular comparison with nil in Go. For example, if v was created
+// by calling ValueOf with an uninitialized interface variable i,
+// i==nil will be true but v.IsNil will panic as v will be the zero
+// Value.
 func (v Value) IsNil() bool {
 	k := v.kind()
 	switch k {