html/template, text/template: clarify template redefinition behavior

Make two important points clearer:

 - Giving a template definition containing
   nothing but spaces has no effect.
 - Giving a template definition containing
   non-spaces can only be done once per template.

Fixes #16912.
Fixes #16913.
Fixes #17360.

Change-Id: Ie3971b83ab148b7c8bb800fe4a21579566378e3e
Reviewed-on: https://go-review.googlesource.com/31459
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
Reviewed-by: Andrew Gerrand <adg@golang.org>

1 files changed, 12 insertions, 3 deletions

diff --git a/src/text/template/template.go b/src/text/template/template.go
index a8ad6279e3..5e3bac465c 100644
--- a/src/text/template/template.go
+++ b/src/text/template/template.go
@@ -181,9 +181,18 @@ func (t *Template) Lookup(name string) *Template {
 	return t.tmpl[name]
 }
 
-// Parse defines the template by parsing the text. Nested template definitions will be
-// associated with the top-level template t. Parse may be called multiple times
-// to parse definitions of templates to associate with t.
+// Parse parses text as a template body for t.
+// Named template definitions ({{define ...}} or {{block ...}} statements) in text
+// define additional templates associated with t and are removed from the
+// definition of t itself.
+//
+// A template definition with a body containing only white space and comments
+// is considered empty and is not recorded as the template's body.
+// Each template can be given a non-empty definition at most once.
+// That is, Parse may be called multiple times to parse definitions of templates
+// to associate with t, but at most one such call can include a non-empty body for
+// t itself, and each named associated template can be given at most one
+// non-empty definition.
 func (t *Template) Parse(text string) (*Template, error) {
 	t.init()
 	t.muFuncs.RLock()