Skip to content

Commit

Permalink
internal/godoc/dochtml: split out deprecated symbols
Browse files Browse the repository at this point in the history 
After parsing the doc, remove deprecated symbols and store them
separately.

This will keep them out of the index and let us display them
separately in the body.

For golang/go#40850

Change-Id: Ia80ef20ef79ddad853e31bad4f4fc9805fd43b2c
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/313031
Trust: Jonathan Amsterdam <jba@google.com>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Jamal Carvalho <jamal@golang.org>
  • Loading branch information
@jba
jba committed Apr 23, 2021
1 parent 750994b commit 2a10a51
Show file tree
Hide file tree
Showing 5 changed files with 217 additions and 279 deletions.
88 changes: 40 additions & 48 deletions content/static/html/doc/outline.tmpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,14 +47,12 @@
</a>
<ul role="group" id="nav-group-functions">
{{range .Funcs}}
{{if not .IsDeprecated}}
<li role="none">
<a href="#{{.Name}}" role="treeitem" aria-level="3" tabindex="-1"
title="{{render_short_synopsis .Decl}}" data-gtm-action="doc outline link clicked">
{{render_short_synopsis .Decl}}
</a>
</li>
{{end}}
<li role="none">
<a href="#{{.Name}}" role="treeitem" aria-level="3" tabindex="-1"
title="{{render_short_synopsis .Decl}}" data-gtm-action="doc outline link clicked">
{{render_short_synopsis .Decl}}
</a>
</li>
{{end}}
</ul>
</li>
Expand All @@ -65,46 +63,40 @@
</a>
<ul role="group" id="nav-group-types">
{{range .Types}}
{{if not .IsDeprecated}}
{{$tname := .Name}}
<li role="none">
{{if or .Funcs .Methods}}
{{$navgroupname := (printf "nav.group.%s" $tname)}}
{{$navgroupid := (safe_id $navgroupname)}}
<a href="#{{$tname}}" role="treeitem" aria-expanded="false" aria-level="3" tabindex="-1"
data-aria-owns="{{$navgroupid}}" data-gtm-action="doc outline link clicked">
type {{$tname}}
</a>
<ul role="group" id="{{$navgroupid}}">
{{range .Funcs}}
{{if not .IsDeprecated}}
<li role="none">
<a href="#{{.Name}}" role="treeitem" aria-level="4" tabindex="-1"
title="{{render_short_synopsis .Decl}}" data-gtm-action="doc outline link clicked">
{{render_short_synopsis .Decl}}
</a>
</li>
{{end}}
{{end}}
{{range .Methods}}
{{if not .IsDeprecated}}
<li role="none">
<a href="#{{$tname}}.{{.Name}}" role="treeitem" aria-level="4" tabindex="-1"
title="{{render_short_synopsis .Decl}}" data-gtm-action="doc outline link clicked">
{{render_short_synopsis .Decl}}
</a>
</li>
{{end}}
{{end}}
</ul>
{{else}}
<a href="#{{$tname}}" role="treeitem" aria-level="3" tabindex="-1"
data-gtm-action="doc outline link clicked">
type {{$tname}}
</a>
{{end}} {{/* if or .Funcs .Methods */}}
</li>
{{end}}
{{$tname := .Name}}
<li role="none">
{{if or .Funcs .Methods}}
{{$navgroupname := (printf "nav.group.%s" $tname)}}
{{$navgroupid := (safe_id $navgroupname)}}
<a href="#{{$tname}}" role="treeitem" aria-expanded="false" aria-level="3" tabindex="-1"
data-aria-owns="{{$navgroupid}}" data-gtm-action="doc outline link clicked">
type {{$tname}}
</a>
<ul role="group" id="{{$navgroupid}}">
{{range .Funcs}}
<li role="none">
<a href="#{{.Name}}" role="treeitem" aria-level="4" tabindex="-1"
title="{{render_short_synopsis .Decl}}" data-gtm-action="doc outline link clicked">
{{render_short_synopsis .Decl}}
</a>
</li>
{{end}}
{{range .Methods}}
<li role="none">
<a href="#{{$tname}}.{{.Name}}" role="treeitem" aria-level="4" tabindex="-1"
title="{{render_short_synopsis .Decl}}" data-gtm-action="doc outline link clicked">
{{render_short_synopsis .Decl}}
</a>
</li>
{{end}}
</ul>
{{else}}
<a href="#{{$tname}}" role="treeitem" aria-level="3" tabindex="-1"
data-gtm-action="doc outline link clicked">
type {{$tname}}
</a>
{{end}} {{/* if or .Funcs .Methods */}}
</li>
{{end}} {{/* range .Types */}}
</ul>
</li>
Expand Down
76 changes: 76 additions & 0 deletions internal/godoc/dochtml/dochtml.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,8 @@ type templateData struct {
*doc.Package
Examples *examples
NoteHeaders map[string]noteHeader
Deprecated *deprecated // extracted from doc.Package; do not appear in outline
Suffix string // suffix for links; always empty (see type deprecated)
}

// Parts contains HTML for each part of the documentation.
Expand Down Expand Up @@ -191,11 +193,13 @@ func renderInfo(ctx context.Context, fset *token.FileSet, p *doc.Package, opt Re
"source_link": sourceLink,
"since_version": sinceVersion,
}
dep := extractDeprecated(p)
data := templateData{
RootURL: "/pkg",
Package: p,
Examples: collectExamples(p),
NoteHeaders: buildNoteHeaders(p.Notes),
Deprecated: dep,
}
return funcs, data, r.Links
}
Expand Down Expand Up @@ -241,6 +245,15 @@ type example struct {
Suffix string // optional suffix name in title case
}

// deprecated holds parts of a doc.Package that are deprecated.
type deprecated struct {
Consts []*doc.Value
Types []*doc.Type
Vars []*doc.Value
Funcs []*doc.Func
Examples []*doc.Example
}

// Code returns an printer.CommentedNode if ex.Comments is non-nil,
// otherwise it returns ex.Code as is.
func (ex *example) Code() interface{} {
Expand Down Expand Up @@ -356,3 +369,66 @@ func versionedPkgPath(pkgPath string, modInfo *ModuleInfo) string {
innerPkgPath := pkgPath[len(modInfo.ModulePath):]
return fmt.Sprintf("%s@%s%s", modInfo.ModulePath, modInfo.ResolvedVersion, innerPkgPath)
}

// extractDeprecated removes and returns all deprecated decls in p.
// It doesn't deal with examples; that is handled elsewhere.
func extractDeprecated(p *doc.Package) *deprecated {
d := &deprecated{}
p.Consts, d.Consts = splitDeprecatedValues(p.Consts)
p.Vars, d.Vars = splitDeprecatedValues(p.Vars)
p.Funcs, d.Funcs = splitDeprecatedFuncs(p.Funcs)
var dfs []*doc.Func
p.Types, d.Types, dfs = splitDeprecatedTypes(p.Types)
// Tack all the deprecated functions and methods from non-deprecated types
// onto the end of the top-level deprecated functions.
d.Funcs = append(d.Funcs, dfs...)
return d
}

// splitDeprecatedValues splits the given values into two lists: non-deprecated
// and deprecated.
func splitDeprecatedValues(xs []*doc.Value) (n, d []*doc.Value) {
for _, x := range xs {
if x.IsDeprecated {
d = append(d, x)
} else {
n = append(n, x)
}
}
return n, d
}

// splitDeprecatedFuncs splits the given funcs into two lists: non-deprecated
// and deprecated.
func splitDeprecatedFuncs(xs []*doc.Func) (n, d []*doc.Func) {
for _, x := range xs {
if x.IsDeprecated {
d = append(d, x)
} else {
n = append(n, x)
}
}
return n, d
}

// splitDeprecatedTypes splits the given types into two lists: non-deprecated
// and deprecated.
// It also returns a list of deprecated functions and methods from
// non-deprecated types.
func splitDeprecatedTypes(xs []*doc.Type) (n, d []*doc.Type, df []*doc.Func) {
for _, x := range xs {
if x.IsDeprecated {
d = append(d, x)
} else {
n = append(n, x)
// Even if a type isn't deprecated, its child decls might be.
// We only care about functions and methods.
var f, m []*doc.Func
x.Funcs, f = splitDeprecatedFuncs(x.Funcs)
df = append(df, f...)
x.Methods, m = splitDeprecatedFuncs(x.Methods)
df = append(df, m...)
}
}
return n, d, df
}
3 changes: 2 additions & 1 deletion internal/godoc/dochtml/testdata/deprecated.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ const BadC = 2

var GoodV = 1

var BadV = 2 // Deprecated: use GoodV.
// Deprecated: use GoodV.
var BadV = 2

func GoodF() {}

Expand Down
Loading

0 comments on commit 2a10a51

Please sign in to comment.