godoc: support go1.19 doc comment syntax

Call go/doc.(*Package).HTML on go1.19 instead of the deprecated go/doc.ToHTML. Change-Id: Ie604d9ace7adc179f7c2e345f17a2e0c0365d1a2 Reviewed-on: https://go-review.googlesource.com/c/tools/+/411381 Run-TryBot: Alessandro Arzilli <alessandro.arzilli@gmail.com> gopls-CI: kokoro <noreply+kokoro@google.com> TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Jonathan Amsterdam <jba@google.com> Reviewed-by: Jenny Rakoczy <jenny@golang.org>
golang · Jul 19, 2022 · 79f3242 · 79f3242
1 parent 2957e9d
commit 79f3242
Show file tree

Hide file tree

Showing 6 changed files with 55 additions and 16 deletions.
diff --git a/godoc/godoc.go b/godoc/godoc.go
@@ -345,11 +345,16 @@ func isDigit(ch rune) bool {
 	return '0' <= ch && ch <= '9' || ch >= utf8.RuneSelf && unicode.IsDigit(ch)
 }
 
-func comment_htmlFunc(comment string) string {
+func comment_htmlFunc(info *PageInfo, comment string) string {
 	var buf bytes.Buffer
 	// TODO(gri) Provide list of words (e.g. function parameters)
 	//           to be emphasized by ToHTML.
-	doc.ToHTML(&buf, comment, nil) // does html-escaping
+
+	// godocToHTML is:
+	// - buf.Write(info.PDoc.HTML(comment)) on go1.19
+	// - go/doc.ToHTML(&buf, comment, nil) on other versions
+	godocToHTML(&buf, info.PDoc, comment)
+
 	return buf.String()
 }
 

diff --git a/godoc/static/package.html b/godoc/static/package.html
@@ -17,7 +17,7 @@
 
 	{{if $.IsMain}}
 		{{/* command documentation */}}
-		{{comment_html .Doc}}
+		{{comment_html $ .Doc}}
 	{{else}}
 		{{/* package documentation */}}
 		<div id="short-nav">
@@ -42,7 +42,7 @@ <h2 class="toggleButton" title="Click to show Overview section">Overview ▹</h2
 			</div>
 			<div class="expanded">
 				<h2 class="toggleButton" title="Click to hide Overview section">Overview ▾</h2>
-				{{comment_html .Doc}}
+				{{comment_html $ .Doc}}
 				{{example_html $ ""}}
 			</div>
 		</div>
@@ -154,14 +154,14 @@ <h2 class="toggleButton" title="Click to hide Internal Call Graph section">Inter
 		{{with .Consts}}
 			<h2 id="pkg-constants">Constants</h2>
 			{{range .}}
-				{{comment_html .Doc}}
+				{{comment_html $ .Doc}}
 				<pre>{{node_html $ .Decl true}}</pre>
 			{{end}}
 		{{end}}
 		{{with .Vars}}
 			<h2 id="pkg-variables">Variables</h2>
 			{{range .}}
-				{{comment_html .Doc}}
+				{{comment_html $ .Doc}}
 				<pre>{{node_html $ .Decl true}}</pre>
 			{{end}}
 		{{end}}
@@ -174,7 +174,7 @@ <h2 id="{{$name_html}}">func <a href="{{posLink_url $ .Decl}}">{{$name_html}}</a
 				{{if $since}}<span title="Added in Go {{$since}}">{{$since}}</span>{{end}}
 			</h2>
 			<pre>{{node_html $ .Decl true}}</pre>
-			{{comment_html .Doc}}
+			{{comment_html $ .Doc}}
 			{{example_html $ .Name}}
 			{{callgraph_html $ "" .Name}}
 
@@ -187,16 +187,16 @@ <h2 id="{{$tname_html}}">type <a href="{{posLink_url $ .Decl}}">{{$tname_html}}<
 				{{$since := since "type" "" .Name $.PDoc.ImportPath}}
 				{{if $since}}<span title="Added in Go {{$since}}">{{$since}}</span>{{end}}
 			</h2>
-			{{comment_html .Doc}}
+			{{comment_html $ .Doc}}
 			<pre>{{node_html $ .Decl true}}</pre>
 
 			{{range .Consts}}
-				{{comment_html .Doc}}
+				{{comment_html $ .Doc}}
 				<pre>{{node_html $ .Decl true}}</pre>
 			{{end}}
 
 			{{range .Vars}}
-				{{comment_html .Doc}}
+				{{comment_html $ .Doc}}
 				<pre>{{node_html $ .Decl true}}</pre>
 			{{end}}
 
@@ -212,7 +212,7 @@ <h3 id="{{$name_html}}">func <a href="{{posLink_url $ .Decl}}">{{$name_html}}</a
 					{{if $since}}<span title="Added in Go {{$since}}">{{$since}}</span>{{end}}
 				</h3>
 				<pre>{{node_html $ .Decl true}}</pre>
-				{{comment_html .Doc}}
+				{{comment_html $ .Doc}}
 				{{example_html $ .Name}}
 				{{callgraph_html $ "" .Name}}
 			{{end}}
@@ -225,7 +225,7 @@ <h3 id="{{$tname_html}}.{{$name_html}}">func ({{html .Recv}}) <a href="{{posLink
 					{{if $since}}<span title="Added in Go {{$since}}">{{$since}}</span>{{end}}
 				</h3>
 				<pre>{{node_html $ .Decl true}}</pre>
-				{{comment_html .Doc}}
+				{{comment_html $ .Doc}}
 				{{$name := printf "%s_%s" $tname .Name}}
 				{{example_html $ $name}}
 				{{callgraph_html $ .Recv .Name}}
@@ -238,7 +238,7 @@ <h3 id="{{$tname_html}}.{{$name_html}}">func ({{html .Recv}}) <a href="{{posLink
 			<h2 id="pkg-note-{{$marker}}">{{noteTitle $marker | html}}s</h2>
 			<ul style="list-style: none; padding: 0;">
 			{{range .}}
-			<li><a href="{{posLink_url $ .}}" style="float: left;">&#x261e;</a> {{comment_html .Body}}</li>
+			<li><a href="{{posLink_url $ .}}" style="float: left;">&#x261e;</a> {{comment_html $ .Body}}</li>
 			{{end}}
 			</ul>
 		{{end}}

diff --git a/godoc/static/searchdoc.html b/godoc/static/searchdoc.html
@@ -15,7 +15,7 @@ <h2 id="{{$key.Name}}">{{$key.Name}}</h2>
 				<a href="/{{$pkg_html}}">{{html .Package}}</a>.<a href="{{$doc_html}}">{{.Name}}</a>
 			{{end}}
 			{{if .Doc}}
-				<p>{{comment_html .Doc}}</p>
+				<p>{{comment_html $ .Doc}}</p>
 			{{else}}
 				<p><em>No documentation available</em></p>
 			{{end}}

diff --git a/godoc/static/static.go b/godoc/static/static.go
diff --git a/godoc/tohtml_go119.go b/godoc/tohtml_go119.go
@@ -0,0 +1,17 @@
+// Copyright 2022 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+//go:build go1.19
+// +build go1.19
+
+package godoc
+
+import (
+	"bytes"
+	"go/doc"
+)
+
+func godocToHTML(buf *bytes.Buffer, pkg *doc.Package, comment string) {
+	buf.Write(pkg.HTML(comment))
+}
diff --git a/godoc/tohtml_other.go b/godoc/tohtml_other.go
@@ -0,0 +1,17 @@
+// Copyright 2022 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+//go:build !go1.19
+// +build !go1.19
+
+package godoc
+
+import (
+	"bytes"
+	"go/doc"
+)
+
+func godocToHTML(buf *bytes.Buffer, pkg *doc.Package, comment string) {
+	doc.ToHTML(buf, comment, nil)
+}