sync.once: document that Do cannot be invoked recursively.

documentation change only.

R=rsc
CC=golang-dev
https://golang.org/cl/1964043

src/pkg/sync/once.go

@@ -13,7 +13,7 @@ type Once struct {
 // Do calls the function f if and only if the method is being called for the
 // first time with this receiver.  In other words, given
 // 	var once Once
-// if once.Do(f) is called multiple times, only the first call will invoke f,
+// if Do(f) is called multiple times, only the first call will invoke f,
 // even if f has a different value in each invocation.  A new instance of
 // Once is required for each function to execute.
 //
@@ -22,6 +22,9 @@ type Once struct {
 // arguments to a function to be invoked by Do:
 // 	config.once.Do(func() { config.init(filename) })
 //
+// Because no call to Do returns until the one call to f returns, if f causes
+// Do to be called, it will deadlock.
+//
 func (o *Once) Do(f func()) {
 	o.m.Lock()
 	defer o.m.Unlock()