cmd/link: give RelocVariant a type, document Reloc

Change-Id: Ib20263405a08674b5e160295fc965da4c8b54b34
Reviewed-on: https://go-review.googlesource.com/29248
Reviewed-by: Ian Lance Taylor <iant@golang.org>

src/cmd/link/internal/ld/link.go

@@ -132,16 +132,27 @@ func (a *Attribute) Set(flag Attribute, value bool) {
 	}
 }
 
+// Reloc is a relocation.
+//
+// The typical Reloc rewrites part of a symbol at offset Off to address Sym.
+// A Reloc is stored in a slice on the Symbol it rewrites.
+//
+// Relocations are generated by the compiler as the type
+// cmd/internal/obj.Reloc, which is encoded into the object file wire
+// format and decoded by the linker into this type. A separate type is
+// used to hold linker-specific state about the relocation.
+//
+// Some relocations are created by cmd/link.
 type Reloc struct {
-	Off     int32
-	Siz     uint8
-	Done    uint8
-	Type    obj.RelocType
-	Variant int32
-	Add     int64
-	Xadd    int64
-	Sym     *Symbol
-	Xsym    *Symbol
+	Off     int32         // offset to rewrite
+	Siz     uint8         // number of bytes to rewrite, 1, 2, or 4
+	Done    uint8         // set to 1 when relocation is complete
+	Variant RelocVariant  // variation on Type
+	Type    obj.RelocType // the relocation type
+	Add     int64         // addend
+	Xadd    int64         // addend passed to external linker
+	Sym     *Symbol       // symbol the relocation addresses
+	Xsym    *Symbol       // symbol passed to external linker
 }
 
 type Auto struct {
@@ -251,9 +262,11 @@ type Pciter struct {
 	done    int
 }
 
-// Reloc.variant
+// RelocVariant is a linker-internal variation on a relocation.
+type RelocVariant uint8
+
 const (
-	RV_NONE = iota
+	RV_NONE RelocVariant = iota
 	RV_POWER_LO
 	RV_POWER_HI
 	RV_POWER_HA
@@ -264,6 +277,6 @@ const (
 	// divided by 2.
 	RV_390_DBL
 
-	RV_CHECK_OVERFLOW = 1 << 8
-	RV_TYPE_MASK      = RV_CHECK_OVERFLOW - 1
+	RV_CHECK_OVERFLOW RelocVariant = 1 << 7
+	RV_TYPE_MASK      RelocVariant = RV_CHECK_OVERFLOW - 1
 )