diff --git a/content/static/html/doc/outline.tmpl b/content/static/html/doc/outline.tmpl index 6886203ba..864deebb0 100644 --- a/content/static/html/doc/outline.tmpl +++ b/content/static/html/doc/outline.tmpl @@ -47,14 +47,12 @@ @@ -65,46 +63,40 @@ diff --git a/internal/godoc/dochtml/dochtml.go b/internal/godoc/dochtml/dochtml.go index 6da7bbe64..09dd1a310 100644 --- a/internal/godoc/dochtml/dochtml.go +++ b/internal/godoc/dochtml/dochtml.go @@ -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. @@ -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 } @@ -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{} { @@ -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 +} diff --git a/internal/godoc/dochtml/testdata/deprecated.go b/internal/godoc/dochtml/testdata/deprecated.go index 2564dcc5a..0382826ab 100644 --- a/internal/godoc/dochtml/testdata/deprecated.go +++ b/internal/godoc/dochtml/testdata/deprecated.go @@ -13,7 +13,8 @@ const BadC = 2 var GoodV = 1 -var BadV = 2 // Deprecated: use GoodV. +// Deprecated: use GoodV. +var BadV = 2 func GoodF() {} diff --git a/internal/godoc/dochtml/testdata/deprecated.golden b/internal/godoc/dochtml/testdata/deprecated.golden index 7c2ff778b..a3b3a1db9 100644 --- a/internal/godoc/dochtml/testdata/deprecated.golden +++ b/internal/godoc/dochtml/testdata/deprecated.golden @@ -12,21 +12,15 @@