all: gofmt
Gofmt to update doc comments to the new formatting.
For golang/go#51082.
Change-Id: I3573e720b522fe41f726d2fb4e3b988ee883872d
Reviewed-on: https://go-review.googlesource.com/c/website/+/399608
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Ian Lance Taylor <iant@google.com>
diff --git a/cmd/screentest/main.go b/cmd/screentest/main.go
index a2a2129..da831db 100644
--- a/cmd/screentest/main.go
+++ b/cmd/screentest/main.go
@@ -4,17 +4,19 @@
/*
Command screentest runs the screentest check for a set of scripts.
- Usage: screentest [flags] [glob]
+
+ Usage: screentest [flags] [glob]
The flags are:
- -u
- update cached screenshots
- -v
- variables provided to script templates as comma separated KEY:VALUE pairs
- -c
- number of testcases to run concurrently
- -d
- chrome debugger url
+
+ -u
+ update cached screenshots
+ -v
+ variables provided to script templates as comma separated KEY:VALUE pairs
+ -c
+ number of testcases to run concurrently
+ -d
+ chrome debugger url
*/
package main
diff --git a/cmd/versionprune/doc.go b/cmd/versionprune/doc.go
index 51ac8aa..6c2a004 100644
--- a/cmd/versionprune/doc.go
+++ b/cmd/versionprune/doc.go
@@ -41,6 +41,5 @@
]
deleting go-discovery/go-dev/20191030t225128
...
-
*/
package main
diff --git a/internal/backport/fmtsort/sort.go b/internal/backport/fmtsort/sort.go
index 7127ba6..e0585dc 100644
--- a/internal/backport/fmtsort/sort.go
+++ b/internal/backport/fmtsort/sort.go
@@ -36,19 +36,18 @@
//
// The ordering rules are more general than with Go's < operator:
//
-// - when applicable, nil compares low
-// - ints, floats, and strings order by <
-// - NaN compares less than non-NaN floats
-// - bool compares false before true
-// - complex compares real, then imag
-// - pointers compare by machine address
-// - channel values compare by machine address
-// - structs compare each field in turn
-// - arrays compare each element in turn.
-// Otherwise identical arrays compare by length.
-// - interface values compare first by reflect.Type describing the concrete type
-// and then by concrete value as described in the previous rules.
-//
+// - when applicable, nil compares low
+// - ints, floats, and strings order by <
+// - NaN compares less than non-NaN floats
+// - bool compares false before true
+// - complex compares real, then imag
+// - pointers compare by machine address
+// - channel values compare by machine address
+// - structs compare each field in turn
+// - arrays compare each element in turn.
+// Otherwise identical arrays compare by length.
+// - interface values compare first by reflect.Type describing the concrete type
+// and then by concrete value as described in the previous rules.
func Sort(mapValue reflect.Value) *SortedMap {
if mapValue.Type().Kind() != reflect.Map {
return nil
diff --git a/internal/backport/html/template/context.go b/internal/backport/html/template/context.go
index 1aacec4..ce21e95 100644
--- a/internal/backport/html/template/context.go
+++ b/internal/backport/html/template/context.go
@@ -80,7 +80,9 @@
// HTML5 parsing algorithm because a single token production in the HTML
// grammar may contain embedded actions in a template. For instance, the quoted
// HTML attribute produced by
-// <div title="Hello {{.World}}">
+//
+// <div title="Hello {{.World}}">
+//
// is a single token in HTML's grammar but in a template spans several nodes.
type state uint8
diff --git a/internal/backport/html/template/doc.go b/internal/backport/html/template/doc.go
index ed2a7e2..cb5bcbe 100644
--- a/internal/backport/html/template/doc.go
+++ b/internal/backport/html/template/doc.go
@@ -12,14 +12,14 @@
For information about how to program the templates themselves, see the
documentation for text/template.
-Introduction
+# Introduction
This package wraps package text/template so you can share its template API
to parse and execute HTML templates safely.
- tmpl, err := template.New("name").Parse(...)
- // Error checking elided
- err = tmpl.Execute(out, data)
+ tmpl, err := template.New("name").Parse(...)
+ // Error checking elided
+ err = tmpl.Execute(out, data)
If successful, tmpl will now be injection-safe. Otherwise, err is an error
defined in the docs for ErrorCode.
@@ -34,38 +34,37 @@
Example
- import "golang.org/x/website/internal/backport/text/template"
- ...
- t, err := template.New("foo").Parse(`{{define "T"}}Hello, {{.}}!{{end}}`)
- err = t.ExecuteTemplate(out, "T", "<script>alert('you have been pwned')</script>")
+ import "golang.org/x/website/internal/backport/text/template"
+ ...
+ t, err := template.New("foo").Parse(`{{define "T"}}Hello, {{.}}!{{end}}`)
+ err = t.ExecuteTemplate(out, "T", "<script>alert('you have been pwned')</script>")
produces
- Hello, <script>alert('you have been pwned')</script>!
+ Hello, <script>alert('you have been pwned')</script>!
but the contextual autoescaping in html/template
- import "html/template"
- ...
- t, err := template.New("foo").Parse(`{{define "T"}}Hello, {{.}}!{{end}}`)
- err = t.ExecuteTemplate(out, "T", "<script>alert('you have been pwned')</script>")
+ import "html/template"
+ ...
+ t, err := template.New("foo").Parse(`{{define "T"}}Hello, {{.}}!{{end}}`)
+ err = t.ExecuteTemplate(out, "T", "<script>alert('you have been pwned')</script>")
produces safe, escaped HTML output
- Hello, <script>alert('you have been pwned')</script>!
+ Hello, <script>alert('you have been pwned')</script>!
-
-Contexts
+# Contexts
This package understands HTML, CSS, JavaScript, and URIs. It adds sanitizing
functions to each simple action pipeline, so given the excerpt
- <a href="/search?q={{.}}">{{.}}</a>
+ <a href="/search?q={{.}}">{{.}}</a>
At parse time each {{.}} is overwritten to add escaping functions as necessary.
In this case it becomes
- <a href="/search?q={{. | urlescaper | attrescaper}}">{{. | htmlescaper}}</a>
+ <a href="/search?q={{. | urlescaper | attrescaper}}">{{. | htmlescaper}}</a>
where urlescaper, attrescaper, and htmlescaper are aliases for internal escaping
functions.
@@ -73,117 +72,113 @@
For these internal escaping functions, if an action pipeline evaluates to
a nil interface value, it is treated as though it were an empty string.
-Namespaced and data- attributes
+# Namespaced and data- attributes
Attributes with a namespace are treated as if they had no namespace.
Given the excerpt
- <a my:href="{{.}}"></a>
+ <a my:href="{{.}}"></a>
At parse time the attribute will be treated as if it were just "href".
So at parse time the template becomes:
- <a my:href="{{. | urlescaper | attrescaper}}"></a>
+ <a my:href="{{. | urlescaper | attrescaper}}"></a>
Similarly to attributes with namespaces, attributes with a "data-" prefix are
treated as if they had no "data-" prefix. So given
- <a data-href="{{.}}"></a>
+ <a data-href="{{.}}"></a>
At parse time this becomes
- <a data-href="{{. | urlescaper | attrescaper}}"></a>
+ <a data-href="{{. | urlescaper | attrescaper}}"></a>
If an attribute has both a namespace and a "data-" prefix, only the namespace
will be removed when determining the context. For example
- <a my:data-href="{{.}}"></a>
+ <a my:data-href="{{.}}"></a>
This is handled as if "my:data-href" was just "data-href" and not "href" as
it would be if the "data-" prefix were to be ignored too. Thus at parse
time this becomes just
- <a my:data-href="{{. | attrescaper}}"></a>
+ <a my:data-href="{{. | attrescaper}}"></a>
As a special case, attributes with the namespace "xmlns" are always treated
as containing URLs. Given the excerpts
- <a xmlns:title="{{.}}"></a>
- <a xmlns:href="{{.}}"></a>
- <a xmlns:onclick="{{.}}"></a>
+ <a xmlns:title="{{.}}"></a>
+ <a xmlns:href="{{.}}"></a>
+ <a xmlns:onclick="{{.}}"></a>
At parse time they become:
- <a xmlns:title="{{. | urlescaper | attrescaper}}"></a>
- <a xmlns:href="{{. | urlescaper | attrescaper}}"></a>
- <a xmlns:onclick="{{. | urlescaper | attrescaper}}"></a>
+ <a xmlns:title="{{. | urlescaper | attrescaper}}"></a>
+ <a xmlns:href="{{. | urlescaper | attrescaper}}"></a>
+ <a xmlns:onclick="{{. | urlescaper | attrescaper}}"></a>
-Errors
+# Errors
See the documentation of ErrorCode for details.
-
-A fuller picture
+# A fuller picture
The rest of this package comment may be skipped on first reading; it includes
details necessary to understand escaping contexts and error messages. Most users
will not need to understand these details.
-
-Contexts
+# Contexts
Assuming {{.}} is `O'Reilly: How are <i>you</i>?`, the table below shows
how {{.}} appears when used in the context to the left.
- Context {{.}} After
- {{.}} O'Reilly: How are <i>you</i>?
- <a title='{{.}}'> O'Reilly: How are you?
- <a href="/{{.}}"> O'Reilly: How are %3ci%3eyou%3c/i%3e?
- <a href="?q={{.}}"> O'Reilly%3a%20How%20are%3ci%3e...%3f
- <a onx='f("{{.}}")'> O\x27Reilly: How are \x3ci\x3eyou...?
- <a onx='f({{.}})'> "O\x27Reilly: How are \x3ci\x3eyou...?"
- <a onx='pattern = /{{.}}/;'> O\x27Reilly: How are \x3ci\x3eyou...\x3f
+ Context {{.}} After
+ {{.}} O'Reilly: How are <i>you</i>?
+ <a title='{{.}}'> O'Reilly: How are you?
+ <a href="/{{.}}"> O'Reilly: How are %3ci%3eyou%3c/i%3e?
+ <a href="?q={{.}}"> O'Reilly%3a%20How%20are%3ci%3e...%3f
+ <a onx='f("{{.}}")'> O\x27Reilly: How are \x3ci\x3eyou...?
+ <a onx='f({{.}})'> "O\x27Reilly: How are \x3ci\x3eyou...?"
+ <a onx='pattern = /{{.}}/;'> O\x27Reilly: How are \x3ci\x3eyou...\x3f
If used in an unsafe context, then the value might be filtered out:
- Context {{.}} After
- <a href="{{.}}"> #ZgotmplZ
+ Context {{.}} After
+ <a href="{{.}}"> #ZgotmplZ
since "O'Reilly:" is not an allowed protocol like "http:".
-
If {{.}} is the innocuous word, `left`, then it can appear more widely,
- Context {{.}} After
- {{.}} left
- <a title='{{.}}'> left
- <a href='{{.}}'> left
- <a href='/{{.}}'> left
- <a href='?dir={{.}}'> left
- <a style="border-{{.}}: 4px"> left
- <a style="align: {{.}}"> left
- <a style="background: '{{.}}'> left
- <a style="background: url('{{.}}')> left
- <style>p.{{.}} {color:red}</style> left
+ Context {{.}} After
+ {{.}} left
+ <a title='{{.}}'> left
+ <a href='{{.}}'> left
+ <a href='/{{.}}'> left
+ <a href='?dir={{.}}'> left
+ <a style="border-{{.}}: 4px"> left
+ <a style="align: {{.}}"> left
+ <a style="background: '{{.}}'> left
+ <a style="background: url('{{.}}')> left
+ <style>p.{{.}} {color:red}</style> left
Non-string values can be used in JavaScript contexts.
If {{.}} is
- struct{A,B string}{ "foo", "bar" }
+ struct{A,B string}{ "foo", "bar" }
in the escaped template
- <script>var pair = {{.}};</script>
+ <script>var pair = {{.}};</script>
then the template output is
- <script>var pair = {"A": "foo", "B": "bar"};</script>
+ <script>var pair = {"A": "foo", "B": "bar"};</script>
See package json to understand how non-string content is marshaled for
embedding in JavaScript contexts.
-
-Typed Strings
+# Typed Strings
By default, this package assumes that all pipelines produce a plain text string.
It adds escaping pipeline stages necessary to correctly and safely embed that
@@ -197,24 +192,23 @@
The template
- Hello, {{.}}!
+ Hello, {{.}}!
can be invoked with
- tmpl.Execute(out, template.HTML(`<b>World</b>`))
+ tmpl.Execute(out, template.HTML(`<b>World</b>`))
to produce
- Hello, <b>World</b>!
+ Hello, <b>World</b>!
instead of the
- Hello, <b>World<b>!
+ Hello, <b>World<b>!
that would have been produced if {{.}} was a regular string.
-
-Security Model
+# Security Model
https://rawgit.com/mikesamuel/sanitized-jquery-templates/trunk/safetemplate.html#problem_definition defines "safe" as used by this package.
diff --git a/internal/backport/html/template/error.go b/internal/backport/html/template/error.go
index 0eae11f..69b0756 100644
--- a/internal/backport/html/template/error.go
+++ b/internal/backport/html/template/error.go
@@ -33,14 +33,17 @@
//
// Output: "ZgotmplZ"
// Example:
-// <img src="{{.X}}">
-// where {{.X}} evaluates to `javascript:...`
+//
+// <img src="{{.X}}">
+// where {{.X}} evaluates to `javascript:...`
+//
// Discussion:
-// "ZgotmplZ" is a special value that indicates that unsafe content reached a
-// CSS or URL context at runtime. The output of the example will be
-// <img src="#ZgotmplZ">
-// If the data comes from a trusted source, use content types to exempt it
-// from filtering: URL(`javascript:...`).
+//
+// "ZgotmplZ" is a special value that indicates that unsafe content reached a
+// CSS or URL context at runtime. The output of the example will be
+// <img src="#ZgotmplZ">
+// If the data comes from a trusted source, use content types to exempt it
+// from filtering: URL(`javascript:...`).
const (
// OK indicates the lack of an error.
OK ErrorCode = iota
diff --git a/internal/backport/html/template/escape.go b/internal/backport/html/template/escape.go
index dfdfea5..e7f3122 100644
--- a/internal/backport/html/template/escape.go
+++ b/internal/backport/html/template/escape.go
@@ -412,13 +412,19 @@
// nudge returns the context that would result from following empty string
// transitions from the input context.
// For example, parsing:
-// `<a href=`
+//
+// `<a href=`
+//
// will end in context{stateBeforeValue, attrURL}, but parsing one extra rune:
-// `<a href=x`
+//
+// `<a href=x`
+//
// will end in context{stateURL, delimSpaceOrTagEnd, ...}.
// There are two transitions that happen when the 'x' is seen:
// (1) Transition from a before-value state to a start-of-value state without
-// consuming any character.
+//
+// consuming any character.
+//
// (2) Consume 'x' and transition past the first value character.
// In this case, nudging produces the context after (1) happens.
func nudge(c context) context {
diff --git a/internal/backport/html/template/html.go b/internal/backport/html/template/html.go
index 356b829..46e9b44 100644
--- a/internal/backport/html/template/html.go
+++ b/internal/backport/html/template/html.go
@@ -84,10 +84,12 @@
// <script>(function () {
// var a = [], d = document.getElementById("d"), i, c, s;
// for (i = 0; i < 0x10000; ++i) {
-// c = String.fromCharCode(i);
-// d.innerHTML = "<span title=" + c + "lt" + c + "></span>"
-// s = d.getElementsByTagName("SPAN")[0];
-// if (!s || s.title !== c + "lt" + c) { a.push(i.toString(16)); }
+//
+// c = String.fromCharCode(i);
+// d.innerHTML = "<span title=" + c + "lt" + c + "></span>"
+// s = d.getElementsByTagName("SPAN")[0];
+// if (!s || s.title !== c + "lt" + c) { a.push(i.toString(16)); }
+//
// }
// document.write(a.join(", "));
// })()</script>
diff --git a/internal/backport/html/template/template.go b/internal/backport/html/template/template.go
index ca77b72..6cc709e 100644
--- a/internal/backport/html/template/template.go
+++ b/internal/backport/html/template/template.go
@@ -65,6 +65,7 @@
//
// missingkey: Control the behavior during execution if a map is
// indexed with a key that is not present in the map.
+//
// "missingkey=default" or "missingkey=invalid"
// The default behavior: Do nothing and continue execution.
// If printed, the result of the index operation is the string
@@ -73,7 +74,6 @@
// The operation returns the zero value for the map type's element.
// "missingkey=error"
// Execution stops immediately with an error.
-//
func (t *Template) Option(opt ...string) *Template {
t.text.Option(opt...)
return t
@@ -369,6 +369,7 @@
// Must is a helper that wraps a call to a function returning (*Template, error)
// and panics if the error is non-nil. It is intended for use in variable initializations
// such as
+//
// var t = template.Must(template.New("name").Parse("html"))
func Must(t *Template, err error) *Template {
if err != nil {
diff --git a/internal/backport/html/template/url.go b/internal/backport/html/template/url.go
index 6f8185a..a0c0012 100644
--- a/internal/backport/html/template/url.go
+++ b/internal/backport/html/template/url.go
@@ -19,15 +19,15 @@
//
// This filter conservatively assumes that all schemes other than the following
// are unsafe:
-// * http: Navigates to a new website, and may open a new window or tab.
-// These side effects can be reversed by navigating back to the
-// previous website, or closing the window or tab. No irreversible
-// changes will take place without further user interaction with
-// the new website.
-// * https: Same as http.
-// * mailto: Opens an email program and starts a new draft. This side effect
-// is not irreversible until the user explicitly clicks send; it
-// can be undone by closing the email program.
+// - http: Navigates to a new website, and may open a new window or tab.
+// These side effects can be reversed by navigating back to the
+// previous website, or closing the window or tab. No irreversible
+// changes will take place without further user interaction with
+// the new website.
+// - https: Same as http.
+// - mailto: Opens an email program and starts a new draft. This side effect
+// is not irreversible until the user explicitly clicks send; it
+// can be undone by closing the email program.
//
// To allow URLs containing other schemes to bypass this filter, developers must
// explicitly indicate that such a URL is expected and safe by encapsulating it
diff --git a/internal/backport/text/template/funcs.go b/internal/backport/text/template/funcs.go
index 11e2e90..23425b4 100644
--- a/internal/backport/text/template/funcs.go
+++ b/internal/backport/text/template/funcs.go
@@ -729,7 +729,9 @@
}
// evalArgs formats the list of arguments into a string. It is therefore equivalent to
+//
// fmt.Sprint(args...)
+//
// except that each argument is indirected (if a pointer), as required,
// using the same rules as the default string evaluation during template
// execution.
diff --git a/internal/backport/text/template/helper.go b/internal/backport/text/template/helper.go
index 8269fa2..481527a 100644
--- a/internal/backport/text/template/helper.go
+++ b/internal/backport/text/template/helper.go
@@ -19,6 +19,7 @@
// Must is a helper that wraps a call to a function returning (*Template, error)
// and panics if the error is non-nil. It is intended for use in variable
// initializations such as
+//
// var t = template.Must(template.New("name").Parse("text"))
func Must(t *Template, err error) *Template {
if err != nil {
diff --git a/internal/backport/text/template/option.go b/internal/backport/text/template/option.go
index addce2d..f2c6681 100644
--- a/internal/backport/text/template/option.go
+++ b/internal/backport/text/template/option.go
@@ -30,6 +30,7 @@
//
// missingkey: Control the behavior during execution if a map is
// indexed with a key that is not present in the map.
+//
// "missingkey=default" or "missingkey=invalid"
// The default behavior: Do nothing and continue execution.
// If printed, the result of the index operation is the string
@@ -38,7 +39,6 @@
// The operation returns the zero value for the map type's element.
// "missingkey=error"
// Execution stops immediately with an error.
-//
func (t *Template) Option(opt ...string) *Template {
t.init()
for _, s := range opt {
diff --git a/internal/backport/text/template/parse/parse.go b/internal/backport/text/template/parse/parse.go
index d92bed5..efae999 100644
--- a/internal/backport/text/template/parse/parse.go
+++ b/internal/backport/text/template/parse/parse.go
@@ -342,7 +342,9 @@
}
// itemList:
+//
// textOrAction*
+//
// Terminates at {{end}} or {{else}}, returned separately.
func (t *Tree) itemList() (list *ListNode, next Node) {
list = t.newList(t.peekNonSpace().pos)
@@ -359,6 +361,7 @@
}
// textOrAction:
+//
// text | comment | action
func (t *Tree) textOrAction() Node {
switch token := t.nextNonSpace(); token.typ {
@@ -381,8 +384,10 @@
}
// Action:
+//
// control
// command ("|" command)*
+//
// Left delim is past. Now get actions.
// First word could be a keyword such as range.
func (t *Tree) action() (n Node) {
@@ -413,7 +418,9 @@
}
// Break:
+//
// {{break}}
+//
// Break keyword is past.
func (t *Tree) breakControl(pos Pos, line int) Node {
if token := t.next(); token.typ != itemRightDelim {
@@ -426,7 +433,9 @@
}
// Continue:
+//
// {{continue}}
+//
// Continue keyword is past.
func (t *Tree) continueControl(pos Pos, line int) Node {
if token := t.next(); token.typ != itemRightDelim {
@@ -439,6 +448,7 @@
}
// Pipeline:
+//
// declarations? command ('|' command)*
func (t *Tree) pipeline(context string, end itemType) (pipe *PipeNode) {
token := t.peekNonSpace()
@@ -550,16 +560,20 @@
}
// If:
+//
// {{if pipeline}} itemList {{end}}
// {{if pipeline}} itemList {{else}} itemList {{end}}
+//
// If keyword is past.
func (t *Tree) ifControl() Node {
return t.newIf(t.parseControl(true, "if"))
}
// Range:
+//
// {{range pipeline}} itemList {{end}}
// {{range pipeline}} itemList {{else}} itemList {{end}}
+//
// Range keyword is past.
func (t *Tree) rangeControl() Node {
r := t.newRange(t.parseControl(false, "range"))
@@ -567,22 +581,28 @@
}
// With:
+//
// {{with pipeline}} itemList {{end}}
// {{with pipeline}} itemList {{else}} itemList {{end}}
+//
// If keyword is past.
func (t *Tree) withControl() Node {
return t.newWith(t.parseControl(false, "with"))
}
// End:
+//
// {{end}}
+//
// End keyword is past.
func (t *Tree) endControl() Node {
return t.newEnd(t.expect(itemRightDelim, "end").pos)
}
// Else:
+//
// {{else}}
+//
// Else keyword is past.
func (t *Tree) elseControl() Node {
// Special case for "else if".
@@ -596,7 +616,9 @@
}
// Block:
+//
// {{block stringValue pipeline}}
+//
// Block keyword is past.
// The name must be something that can evaluate to a string.
// The pipeline is mandatory.
@@ -624,7 +646,9 @@
}
// Template:
+//
// {{template stringValue pipeline}}
+//
// Template keyword is past. The name must be something that can evaluate
// to a string.
func (t *Tree) templateControl() Node {
@@ -655,7 +679,9 @@
}
// command:
+//
// operand (space operand)*
+//
// space-separated arguments up to a pipeline character or right delimiter.
// we consume the pipe character but leave the right delim to terminate the action.
func (t *Tree) command() *CommandNode {
@@ -685,7 +711,9 @@
}
// operand:
+//
// term .Field*
+//
// An operand is a space-separated component of a command,
// a term possibly followed by field accesses.
// A nil return means the next item is not an operand.
@@ -719,12 +747,14 @@
}
// term:
+//
// literal (number, string, nil, boolean)
// function (identifier)
// .
// .Field
// $
// '(' pipeline ')'
+//
// A term is a simple "expression".
// A nil return means the next item is not a term.
func (t *Tree) term() Node {
diff --git a/internal/dl/dl.go b/internal/dl/dl.go
index cff8914..8d6013f 100644
--- a/internal/dl/dl.go
+++ b/internal/dl/dl.go
@@ -9,17 +9,20 @@
// It is designed to run only on the instance of godoc that serves golang.org.
//
// The package also serves the list of downloads and individual files at:
-// https://golang.org/dl/
-// https://golang.org/dl/{file}
+//
+// https://golang.org/dl/
+// https://golang.org/dl/{file}
//
// An optional query param, mode=json, serves the list of stable release
// downloads in JSON format:
-// https://golang.org/dl/?mode=json
+//
+// https://golang.org/dl/?mode=json
//
// An additional query param, include=all, when used with the mode=json
// query param, will serve a full list of available downloads, including
// unstable, stable, and archived releases, in JSON format:
-// https://golang.org/dl/?mode=json&include=all
+//
+// https://golang.org/dl/?mode=json&include=all
//
// Releases returned in JSON modes are sorted by version, newest to oldest.
package dl
diff --git a/internal/dl/server.go b/internal/dl/server.go
index 421c9d5..e9d0dde 100644
--- a/internal/dl/server.go
+++ b/internal/dl/server.go
@@ -79,6 +79,7 @@
}
// dl.gob was generated 2021-11-08 from the live server data, for offline testing.
+//
//go:embed dl.gob
var dlGob []byte
diff --git a/internal/history/history.go b/internal/history/history.go
index 4a2d985..e25485c 100644
--- a/internal/history/history.go
+++ b/internal/history/history.go
@@ -147,18 +147,17 @@
//
// The different special cases are:
//
-// c1
-// c1 and c2
-// c1, c2, and c3
+// c1
+// c1 and c2
+// c1, c2, and c3
//
-// the p1 package
-// the p1 and p2 packages
-// the p1, p2, and p3 packages
+// the p1 package
+// the p1 and p2 packages
+// the p1, p2, and p3 packages
//
-// c1 and [1 package]
-// c1, and [2 or more packages]
-// c1, c2, and [1 or more packages]
-//
+// c1 and [1 package]
+// c1, and [2 or more packages]
+// c1, c2, and [1 or more packages]
func (f *FixSummary) ComponentsAndPackages() template.HTML {
var buf strings.Builder
diff --git a/internal/screentest/screentest.go b/internal/screentest/screentest.go
index bca7a8e..21912c0 100644
--- a/internal/screentest/screentest.go
+++ b/internal/screentest/screentest.go
@@ -5,7 +5,7 @@
// Package screentest implements script-based visual diff testing
// for webpages.
//
-// Scripts
+// # Scripts
//
// A script is a template file containing a sequence of testcases, separated by
// blank lines. Lines beginning with # characters are ignored as comments. A
@@ -13,99 +13,98 @@
// with the dimensions of the screenshots to be compared. For example, here is
// a trivial script:
//
-// compare https://go.dev {{.ComparisonURL}}
-// pathname /about
-// capture fullscreen
+// compare https://go.dev {{.ComparisonURL}}
+// pathname /about
+// capture fullscreen
//
// This script has a single testcase. The first line sets the origin servers to
// compare. The second line sets the page to visit at each origin. The last line
// captures fullpage screenshots of the pages and generates a diff image if they
// do not match.
//
-// Keywords
+// # Keywords
//
// Use windowsize WIDTHxHEIGHT to set the default window size for all testcases
// that follow.
//
-// windowsize 540x1080
+// windowsize 540x1080
//
// Use compare ORIGIN ORIGIN to set the origins to compare.
//
-// compare https://go.dev http://localhost:6060
+// compare https://go.dev http://localhost:6060
//
// Use header KEY:VALUE to add headers to requests
//
-// header Authorization: Bearer token
+// header Authorization: Bearer token
//
// Add the ::cache suffix to cache the images from an origin for subsequent
// test runs.
//
-// compare https://go.dev::cache http://localhost:6060
+// compare https://go.dev::cache http://localhost:6060
//
// Use block URL ... to set URL patterns to block. Wildcards ('*') are allowed.
//
-// block https://codecov.io/* https://travis-ci.com/*
+// block https://codecov.io/* https://travis-ci.com/*
//
// Use output DIRECTORY to set the output directory for diffs and cached images.
//
-// output testdata/snapshots
+// output testdata/snapshots
//
// USE output BUCKETNAME for screentest to upload test output to a Cloud Storage bucket.
// The bucket must already exist prior to running the tests.
//
-// output gs://bucket-name
+// output gs://bucket-name
//
// Values set with the keywords above apply to all testcases that follow. Values set with
// the keywords below reset each time the test keyword is used.
//
// Use test NAME to create a name for the testcase.
//
-// test about page
+// test about page
//
// Use pathname PATH to set the page to visit at each origin. If no
// test name is set, PATH will be used as the name for the test.
//
-// pathname /about
+// pathname /about
//
// Use status CODE to set an expected HTTP status code. The default is 200.
//
-// status 404
+// status 404
//
// Use click SELECTOR to add a click an element on the page.
//
-// click button.submit
+// click button.submit
//
// Use wait SELECTOR to wait for an element to appear.
//
-// wait [role="treeitem"][aria-expanded="true"]
+// wait [role="treeitem"][aria-expanded="true"]
//
// Use capture [SIZE] [ARG] to create a testcase with the properties
// defined above.
//
-// capture fullscreen 540x1080
+// capture fullscreen 540x1080
//
// When taking an element screenshot provide a selector.
//
-// capture element header
+// capture element header
//
// Chain capture commands to create multiple testcases for a single page.
//
-// windowsize 1536x960
-// compare https://go.dev::cache http://localhost:6060
-// output testdata/snapshots
+// windowsize 1536x960
+// compare https://go.dev::cache http://localhost:6060
+// output testdata/snapshots
//
-// test homepage
-// pathname /
-// capture viewport
-// capture viewport 540x1080
-// capture viewport 400x1000
+// test homepage
+// pathname /
+// capture viewport
+// capture viewport 540x1080
+// capture viewport 400x1000
//
-// test about page
-// pathname /about
-// capture viewport
-// capture viewport 540x1080
-// capture viewport 400x1000
-//
+// test about page
+// pathname /about
+// capture viewport
+// capture viewport 540x1080
+// capture viewport 400x1000
package screentest
import (
diff --git a/internal/short/short.go b/internal/short/short.go
index 44a69a2..8cbbb59 100644
--- a/internal/short/short.go
+++ b/internal/short/short.go
@@ -54,7 +54,9 @@
}
// linkHandler services requests to short URLs.
-// https://go.dev/s/key[/remaining/path]
+//
+// https://go.dev/s/key[/remaining/path]
+//
// It consults memcache and datastore for the Link for key.
// It then sends a redirects or an error message.
// If the remaining path part is not empty, the redirects
diff --git a/internal/tmplfunc/tmpl.go b/internal/tmplfunc/tmpl.go
index 0659d89..63ab5a2 100644
--- a/internal/tmplfunc/tmpl.go
+++ b/internal/tmplfunc/tmpl.go
@@ -18,7 +18,7 @@
//
// {{template "link" (dict "url" "https://golang.org" "text" "the Go language")}}
//
-// Function Definitions
+// # Function Definitions
//
// The function installed for a given template depends on the name of the
// defined template, which can include not just a function name but also
@@ -52,9 +52,9 @@
//
// {{define "link url text?"}}<a href="{{.url}}">{{or .text .url}}</a>{{end}}
//
-// The Go home page is {{link "https://golang.org"}}.
+// The Go home page is {{link "https://golang.org"}}.
//
-// Usage
+// # Usage
//
// This package is meant to be used with templates from either the
// text/template or html/template packages. Given a *template.Template
diff --git a/internal/web/site.go b/internal/web/site.go
index f6269b0..e1fba85 100644
--- a/internal/web/site.go
+++ b/internal/web/site.go
@@ -5,7 +5,7 @@
// Package web implements a basic web site serving framework.
// The two fundamental types in this package are Site and Page.
//
-// Sites
+// # Sites
//
// A Site is an http.Handler that serves requests from a file system.
// Use NewSite(fsys) to create a new Site.
@@ -14,7 +14,7 @@
// which holds files to be served as well as templates for
// converting Markdown or HTML fragments into full HTML pages.
//
-// Pages
+// # Pages
//
// A Page, which is a map[string]interface{}, is the raw data that a Site renders into a web page.
// Typically a Page is loaded from a *.html or *.md file in the file system fsys, although
@@ -54,14 +54,14 @@
// In addition to these explicit key-value pairs, pages loaded from the file system
// have a few implicit key-value pairs added by the page loading process:
//
-// - File: the path in fsys to the file containing the page
-// - FileData: the file body, with the key-value metadata stripped
-// - URL: this page's URL path (/x/y/z for x/y/z.md, /x/y/ for x/y/index.md)
+// - File: the path in fsys to the file containing the page
+// - FileData: the file body, with the key-value metadata stripped
+// - URL: this page's URL path (/x/y/z for x/y/z.md, /x/y/ for x/y/index.md)
//
// The key “Content” is added during during the rendering process.
// See “Page Rendering” for details.
//
-// Page Rendering
+// # Page Rendering
//
// A Page's content is rendered in two steps: conversion to content, and framing of content.
//
@@ -106,7 +106,7 @@
// if there is no layout-specific template,
// the content will still be rendered.
//
-// Page Template Functions
+// # Page Template Functions
//
// In this web server, templates can themselves be invoked as functions.
// See https://pkg.go.dev/rsc.io/tmplfunc for more details about that feature.
@@ -194,7 +194,7 @@
// function in these packages (except path.Split, which has more than one non-error result
// and would not be invokable). For example, “{{strings.ToUpper "abc"}}”.
//
-// Serving Requests
+// # Serving Requests
//
// A Site is an http.Handler that serves requests by consulting the underlying
// file system and constructing and rendering pages, as well as serving binary
@@ -270,7 +270,7 @@
// where err is the “not exist” error returned by fs.Stat(fsys, p).
// (See also the “Serving Errors” section below.)
//
-// Serving Dynamic Requests
+// # Serving Dynamic Requests
//
// Of course, a web site may wish to serve more than static content.
// To allow dynamically generated web pages to make use of page
@@ -278,7 +278,7 @@
// called with a dynamically generated Page value, which will then
// be rendered and served as the result of the request.
//
-// Serving Errors
+// # Serving Errors
//
// If an error occurs while serving a request r,
// the Site responds with the rendering of
@@ -295,7 +295,6 @@
//
// The Site.ServeError and Site.ServeErrorStatus methods provide a way
// for dynamic servers to generate similar responses.
-//
package web
import (
@@ -378,7 +377,6 @@
// "layout": error,
// "error": err,
// }
-//
func (s *Site) ServeErrorStatus(w http.ResponseWriter, r *http.Request, err error, status int) {
s.serveErrorStatus(w, r, err, status, false)
}
diff --git a/internal/webtest/webtest.go b/internal/webtest/webtest.go
index 86bd868..cdd22c8 100644
--- a/internal/webtest/webtest.go
+++ b/internal/webtest/webtest.go
@@ -21,7 +21,7 @@
// They run the entire script and return a multiline error summarizing
// any problems.
//
-// Scripts
+// # Scripts
//
// A script is a text file containing a sequence of cases, separated by blank lines.
// Lines beginning with # characters are ignored as comments.
@@ -36,7 +36,7 @@
// In this case, the request is a GET of the URL /, and the response body
// must contain the text “Go is an open source programming language”.
//
-// Requests
+// # Requests
//
// Each case begins with a line starting with GET, HEAD, or POST.
// The argument (the remainder of the line) is the URL to be used in the request.
@@ -79,7 +79,7 @@
// This stanza sends a request with post body “x=hello+world&y=Go+%26+You”.
// (The multiline syntax is described in detail below.)
//
-// Checks
+// # Checks
//
// By default, a stanza like the ones above checks only that the request
// succeeds in returning a response with HTTP status code 200 (OK).
@@ -130,7 +130,7 @@
// body ~ Got1xxResponse.*// Go 1\.11
// body ~ GotFirstResponseByte func\(\)\s*$
//
-// Multiline Texts
+// # Multiline Texts
//
// The <text> in a request or check line can take a multiline form,
// by omitting it from the original line and then specifying the text
@@ -145,7 +145,6 @@
// body ==
// <!DOCTYPE html>
// hello, world
-//
package webtest
import (
