reflect: document Method(ByName) w.r.t dead code elimination

The behavior is described in src/cmd/link/internal/ld/deadcode.go
but is not otherwise documented. Since the usage of those functions
could have significant caveats (longer builds, larger binaries),
we are informing the user.

Change-Id: I87571dd14aa16d7aac59fe45dfc52cb7c5b956c1
Reviewed-on: https://go-review.googlesource.com/c/go/+/658255
Auto-Submit: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: David Chase <drchase@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>

diff --git a/src/reflect/type.go b/src/reflect/type.go
index b6fc99a9347cd450806ab3e45c55ecccd156a5e2..0004cab985a1f8aa2b063fdabeaa5be023d5f307 100644 (file)
--- a/src/reflect/type.go
+++ b/src/reflect/type.go
@@ -59,6 +59,9 @@ type Type interface {
        // method signature, without a receiver, and the Func field is nil.
        //
        // Methods are sorted in lexicographic order.
+       //
+       // Calling this method will force the linker to retain all exported methods in all packages.
+       // This may make the executable binary larger but will not affect execution time.
        Method(int) Method
 
        // MethodByName returns the method with that name in the type's
@@ -69,6 +72,10 @@ type Type interface {
        //
        // For an interface type, the returned Method's Type field gives the
        // method signature, without a receiver, and the Func field is nil.
+       //
+       // Calling this method will cause the linker to retain all methods with this name in all packages.
+       // If the linker can't determine the name, it will retain all exported methods.
+       // This may make the executable binary larger but will not affect execution time.
        MethodByName(string) (Method, bool)
 
        // NumMethod returns the number of methods accessible using Method.

diff --git a/src/reflect/value.go b/src/reflect/value.go
index 881664d21ad6f395a421605d6f2663d750682cdb..6e062a56d1c7ac2674ffa6908a4f2d44910064be 100644 (file)
--- a/src/reflect/value.go
+++ b/src/reflect/value.go
@@ -1799,6 +1799,9 @@ func copyVal(typ *abi.Type, fl flag, ptr unsafe.Pointer) Value {
 // The arguments to a Call on the returned function should not include
 // a receiver; the returned function will always use v as the receiver.
 // Method panics if i is out of range or if v is a nil interface value.
+//
+// Calling this method will force the linker to retain all exported methods in all packages.
+// This may make the executable binary larger but will not affect execution time.
 func (v Value) Method(i int) Value {
        if v.typ() == nil {
                panic(&ValueError{"reflect.Value.Method", Invalid})
@@ -1835,6 +1838,10 @@ func (v Value) NumMethod() int {
 // The arguments to a Call on the returned function should not include
 // a receiver; the returned function will always use v as the receiver.
 // It returns the zero Value if no method was found.
+//
+// Calling this method will cause the linker to retain all methods with this name in all packages.
+// If the linker can't determine the name, it will retain all exported methods.
+// This may make the executable binary larger but will not affect execution time.
 func (v Value) MethodByName(name string) Value {
        if v.typ() == nil {
                panic(&ValueError{"reflect.Value.MethodByName", Invalid})