Skip to content

Commit

Permalink
gopls/internal/golang: provide version info for stdlib in pkgdoc
Browse files Browse the repository at this point in the history
The available versions are provided for functions and methods.
Same as https://pkg.go.dev/

1. The std lib version is only available for FUNC, METHOD, TYPE. Not
   available for CONST, VAR & FIELD. Because those types do not have
   dedicated HTML element, declarations are shown only as source code.
2. Introduce css element stdlibVersion which contains the styles needed.

For golang/go#67159

Change-Id: I4b4f469a858a1aca6598f2abed6f990ab1931b00
Reviewed-on: https://go-review.googlesource.com/c/tools/+/595855
Reviewed-by: Robert Findley <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>
  • Loading branch information
h9jiang committed Jul 2, 2024
1 parent fcf5463 commit 0e7ccc0
Showing 1 changed file with 23 additions and 6 deletions.
29 changes: 23 additions & 6 deletions gopls/internal/golang/pkgdoc.go
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ import (
"golang.org/x/tools/gopls/internal/util/safetoken"
"golang.org/x/tools/gopls/internal/util/slices"
"golang.org/x/tools/gopls/internal/util/typesutil"
"golang.org/x/tools/internal/stdlib"
"golang.org/x/tools/internal/typesinternal"
)

Expand Down Expand Up @@ -415,6 +416,12 @@ header {
padding: 0.3em;
}
.Documentation-sinceVersion {
font-weight: normal;
color: #808080;
float: right;
}
#pkgsite { height: 1.5em; }
#hdr-Selector {
Expand Down Expand Up @@ -782,15 +789,25 @@ window.addEventListener('load', function() {
values(docpkg.Vars)
}

// addedInHTML returns an HTML division containing the Go release version at
// which this obj became available.
addedInHTML := func(obj types.Object) string {
if sym := StdSymbolOf(obj); sym != nil && sym.Version != stdlib.Version(0) {
return fmt.Sprintf("<span class='Documentation-sinceVersion'>added in %v</span>", sym.Version)
}
return ""
}

// package-level functions
fmt.Fprintf(&buf, "<h2 id='hdr-Functions'>Functions</h2>\n")
// funcs emits a list of package-level functions,
// possibly organized beneath the type they construct.
funcs := func(funcs []*doc.Func) {
for _, docfn := range funcs {
obj := scope.Lookup(docfn.Name).(*types.Func)
fmt.Fprintf(&buf, "<h3 id='%s'>func %s</h3>\n",
docfn.Name, objHTML(pkg.FileSet(), web, obj))

fmt.Fprintf(&buf, "<h3 id='%s'>func %s %s</h3>\n",
docfn.Name, objHTML(pkg.FileSet(), web, obj), addedInHTML(obj))

// decl: func F(params) results
fmt.Fprintf(&buf, "<pre class='code'>%s</pre>\n",
Expand All @@ -808,8 +825,8 @@ window.addEventListener('load', function() {
tname := scope.Lookup(doctype.Name).(*types.TypeName)

// title and source link
fmt.Fprintf(&buf, "<h3 id='%s'>type %s</a></h3>\n",
doctype.Name, objHTML(pkg.FileSet(), web, tname))
fmt.Fprintf(&buf, "<h3 id='%s'>type %s %s</h3>\n",
doctype.Name, objHTML(pkg.FileSet(), web, tname), addedInHTML(tname))

// declaration
// TODO(adonovan): excise non-exported struct fields somehow.
Expand All @@ -828,10 +845,10 @@ window.addEventListener('load', function() {
// methods on T
for _, docmethod := range doctype.Methods {
method, _, _ := types.LookupFieldOrMethod(tname.Type(), true, tname.Pkg(), docmethod.Name)
fmt.Fprintf(&buf, "<h4 id='%s.%s'>func (%s) %s</h4>\n",
fmt.Fprintf(&buf, "<h4 id='%s.%s'>func (%s) %s %s</h4>\n",
doctype.Name, docmethod.Name,
docmethod.Orig, // T or *T
objHTML(pkg.FileSet(), web, method))
objHTML(pkg.FileSet(), web, method), addedInHTML(method))

// decl: func (x T) M(params) results
fmt.Fprintf(&buf, "<pre class='code'>%s</pre>\n",
Expand Down

0 comments on commit 0e7ccc0

Please sign in to comment.