cmd/link: document generator symbols more

And make the existing docs easier to parse.

In particular, document the interaction with relocations.

Change-Id: I97579f88d9248c12e64af723a946959b88d4b674
Reviewed-on: https://go-review.googlesource.com/c/go/+/351112
Trust: Josh Bleecher Snyder <[email protected]>
Run-TryBot: Josh Bleecher Snyder <[email protected]>
TryBot-Result: Go Bot <[email protected]>
Reviewed-by: Cherry Mui <[email protected]>

Author: josharian

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

@@ -148,12 +148,18 @@ func (ctxt *Link) MaxVersion() int {
 }
 
 // generatorFunc is a convenience type.
-// Linker created symbols that are large, and shouldn't really live in the
-// heap can define a generator function, and their bytes can be generated
+// Some linker-created Symbols are large and shouldn't really live in the heap.
+// Such Symbols can define a generator function. Their bytes can be generated
 // directly in the output mmap.
 //
-// Generator symbols shouldn't grow the symbol size, and might be called in
-// parallel in the future.
+// Relocations are applied prior to emitting generator Symbol contents.
+// Generator Symbols that require relocations can be written in two passes.
+// The first pass, at Symbol creation time, adds only relocations.
+// The second pass, at content generation time, adds the rest.
+// See generateFunctab for an example.
+//
+// Generator functions shouldn't grow the Symbol size.
+// Generator functions must be safe for concurrent use.
 //
 // Generator Symbols have their Data set to the mmapped area when the
 // generator is called.