exp/template/html: add doc comments for undocumented Err... constants.

Does some TODOs and changes the term "div" in an error message
to "division" to avoid confusion with "<div>".

R=nigeltao, r
CC=golang-dev
https://golang.org/cl/5141047

diff --git a/src/pkg/exp/template/html/error.go b/src/pkg/exp/template/html/error.go
index f06251d6047f1ba3021f944bcf16451ab43fdc4b..5515bfe68dd2b5859b3cb0517a1691a385e19d35 100644 (file)
--- a/src/pkg/exp/template/html/error.go
+++ b/src/pkg/exp/template/html/error.go
@@ -40,7 +40,7 @@ const (
        // OK indicates the lack of an error.
        OK ErrorCode = iota
 
-       // ErrorAmbigContext: "... appears in an ambiguous URL context"
+       // ErrAmbigContext: "... appears in an ambiguous URL context"
        // Example:
        //   <a href="
        //      {{if .C}}
@@ -57,7 +57,18 @@ const (
        //   <a href="{{if .C}}/path/{{.X}}{{else}}/search?q={{.X}}">
        ErrAmbigContext
 
-       // TODO: document
+       // ErrBadHTML: "expected space, attr name, or end of tag, but got ...",
+       //   "... in unquoted attr", "... in attribute name"
+       // Example:
+       //   <a href = /search?q=foo>
+       //   <href=foo>
+       //   <form na<e=...>
+       //   <option selected<
+       // Discussion:
+       //   This is often due to a typo in an HTML element, but some runes
+       //   are banned in tag names, attribute names, and unquoted attribute
+       //   values because they can tickle parser ambiguities.
+       //   Quoting all attributes is the best policy.
        ErrBadHTML
 
        // ErrBranchEnd: "{{if}} branches end in different contexts"
@@ -115,8 +126,8 @@ const (
 
        // ErrNoSuchTemplate: "no such template ..."
        // Examples:
-       //    {{define "main"}}<div {{template "attrs"}}>{{end}}
-       //    {{define "attrs"}}href="{{.URL}}"{{end}}
+       //   {{define "main"}}<div {{template "attrs"}}>{{end}}
+       //   {{define "attrs"}}href="{{.URL}}"{{end}}
        // Discussion:
        //   EscapeSet looks through template calls to compute the context.
        //   Here the {{.URL}} in "attrs" must be treated as a URL when called
@@ -124,7 +135,16 @@ const (
        //   EscapeSet(&set, "main") is called, this error will arise.
        ErrNoSuchTemplate
 
-       // TODO: document
+       // ErrOutputContext: "cannot compute output context for template ..."
+       // Examples:
+       //   {{define "t"}}{{if .T}}{{template "t" .T}}{{end}}{{.H}}",{{end}}
+       // Discussion:
+       //   A recursive template does not end in the same context in which it
+       //   starts, and a reliable output context cannot be computed.
+       //   Look for typos in the named template.
+       //   If the template should not be called in the named start context,
+       //   look for calls to that template in unexpected contexts.
+       //   Maybe refactor recursive templates to not be recursive.
        ErrOutputContext
 
        // ErrPartialCharset: "unfinished JS regexp charset in ..."
@@ -161,7 +181,19 @@ const (
        //     <p class=foo<p class=bar
        ErrRangeLoopReentry
 
-       // TODO: document
+       // ErrSlashAmbig: '/' could start a division or regexp.
+       // Example:
+       //   <script>
+       //     {{if .C}}var x = 1{{end}}
+       //     /-{{.N}}/i.test(x) ? doThis : doThat();
+       //   </script>
+       // Discussion:
+       //   The example above could produce `var x = 1/-2/i.test(s)...`
+       //   in which the first '/' is a mathematical division operator or it
+       //   could produce `/-2/i.test(s)` in which the first '/' starts a
+       //   regexp literal.
+       //   Look for missing semicolons inside branches, and maybe add
+       //   parentheses to make it clear which interpretation you intend.
        ErrSlashAmbig
 )
 

diff --git a/src/pkg/exp/template/html/escape_test.go b/src/pkg/exp/template/html/escape_test.go
index ea7d3bdb04999cc8b601889d311e6ac7ac6df687..d251cdb9a31b2b4e5529f773110640d3fd8e5322 100644 (file)
--- a/src/pkg/exp/template/html/escape_test.go
+++ b/src/pkg/exp/template/html/escape_test.go
@@ -891,7 +891,7 @@ func TestErrors(t *testing.T) {
                        // or `/-1\.5/i.test(x)` which is a method call on a
                        // case insensitive regular expression.
                        `<script>{{if false}}var x = 1{{end}}/-{{"1.5"}}/i.test(x)</script>`,
-                       `'/' could start div or regexp: "/-"`,
+                       `'/' could start a division or regexp: "/-"`,
                },
                {
                        `{{template "foo"}}`,

diff --git a/src/pkg/exp/template/html/transition.go b/src/pkg/exp/template/html/transition.go
index b8e02b239c91e8b6e50af2de4ad1c393f4335955..d3c8a0529184bababe1edfd70299ad5fc5a3f0e5 100644 (file)
--- a/src/pkg/exp/template/html/transition.go
+++ b/src/pkg/exp/template/html/transition.go
@@ -251,7 +251,7 @@ func tJS(c context, s []byte) (context, int) {
                default:
                        return context{
                                state: stateError,
-                               err:   errorf(ErrSlashAmbig, 0, "'/' could start div or regexp: %.32q", s[i:]),
+                               err:   errorf(ErrSlashAmbig, 0, "'/' could start a division or regexp: %.32q", s[i:]),
                        }, len(s)
                }
        default: