code review 5716057: reflect: expand doc for Value.Interface

src/pkg/reflect/value.go

 // Copyright 2009 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 package reflect
 
 import (
         "math"
         "runtime"
         "strconv"
@@ skipping 782 matching lines @@
 }
 
 // CanInterface returns true if Interface can be used without panicking.
 func (v Value) CanInterface() bool {
         if v.flag == 0 {
                 panic(&ValueError{"reflect.Value.CanInterface", Invalid})
         }
         return v.flag&(flagMethod|flagRO) == 0
 }
 
-// Interface returns v's value as an interface{}.
+// Interface returns v's current value as an interface{}.
+// It is equivalent to:
+//      var i interface{} = (v's underlying value)
 // If v is a method obtained by invoking Value.Method
 // (as opposed to Type.Method), Interface cannot return an
 // interface value, so it panics.
 // It also panics if the Value was obtained by accessing
 // unexported struct fields.
-func (v Value) Interface() interface{} {
+func (v Value) Interface() (i interface{}) {
         return valueInterface(v, true)
 }
 
 func valueInterface(v Value, safe bool) interface{} {
         if v.flag == 0 {
                 panic(&ValueError{"reflect.Value.Interface", 0})
         }
         if v.flag&flagMethod != 0 {
                 panic("reflect.Value.Interface: cannot create interface value for method with bound receiver")
         }
@@ skipping 971 matching lines @@
 func escapes(x interface{}) {
         if dummy.b {
                 dummy.x = x
         }
 }
 
 var dummy struct {
         b bool
         x interface{}
 }