internal/godoc/dochtml: remove deprecated symbols from index

If a symbol is deprecated, don't display it in the outline. This CL only handles the non-mobile outline. For golang/go#40850 Change-Id: Ic758ffa5d811b2a2287c550dddadc38d0a322937 Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/312691 Trust: Jonathan Amsterdam <jba@google.com> Run-TryBot: Jonathan Amsterdam <jba@google.com> TryBot-Result: kokoro <noreply+kokoro@google.com> Reviewed-by: Jamal Carvalho <jamal@golang.org>
golang · Apr 22, 2021 · e0ffc7d · e0ffc7d
1 parent 2ccf768
commit e0ffc7d
Show file tree

Hide file tree

Showing 6 changed files with 188 additions and 67 deletions.
diff --git a/content/static/html/doc/outline.tmpl b/content/static/html/doc/outline.tmpl
@@ -36,12 +36,14 @@
       </a>
       <ul role="group" id="nav-group-functions">
         {{range .Funcs}}
-          <li role="none">
-            <a href="#{{.Name}}" role="treeitem" aria-level="3" tabindex="-1"
-                 title="{{render_short_synopsis .Decl}}">
-              {{render_short_synopsis .Decl}}
-            </a>
-          </li>
+          {{if not .IsDeprecated}}
+              <li role="none">
+                <a href="#{{.Name}}" role="treeitem" aria-level="3" tabindex="-1"
+                     title="{{render_short_synopsis .Decl}}">
+                  {{render_short_synopsis .Decl}}
+                </a>
+              </li>
+          {{end}}
         {{end}}
       </ul>
     </li>
@@ -52,39 +54,45 @@
       </a>
       <ul role="group" id="nav-group-types">
         {{range .Types}}
-          {{$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}}">
-                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}}">
-                      {{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}}">
-                      {{render_short_synopsis .Decl}}
-                    </a>
-                  </li>
-                {{end}}
-              </ul>
-            {{else}}
-              <a href="#{{$tname}}" role="treeitem" aria-level="3" tabindex="-1">
-                type {{$tname}}
-              </a>
-            {{end}} {{/* if or .Funcs .Methods */}}
-          </li>
+          {{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}}">
+                  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}}">
+                          {{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}}">
+                          {{render_short_synopsis .Decl}}
+                        </a>
+                      </li>
+                    {{end}}
+                  {{end}}
+                </ul>
+              {{else}}
+                <a href="#{{$tname}}" role="treeitem" aria-level="3" tabindex="-1">
+                  type {{$tname}}
+                </a>
+              {{end}} {{/* if or .Funcs .Methods */}}
+            </li>
+          {{end}}
         {{end}} {{/* range .Types */}}
       </ul>
     </li>

diff --git a/internal/godoc/dochtml/dochtml_test.go b/internal/godoc/dochtml/dochtml_test.go
@@ -34,16 +34,18 @@ var (
 	hasExactText = htmlcheck.HasExactText
 )
 
+var testRenderOptions = RenderOptions{
+	FileLinkFunc:     func(string) string { return "file" },
+	SourceLinkFunc:   func(ast.Node) string { return "src" },
+	SinceVersionFunc: func(string) string { return "" },
+}
+
 func TestRenderParts(t *testing.T) {
 	LoadTemplates(templateSource)
 	fset, d := mustLoadPackage("everydecl")
 
 	ctx := context.Background()
-	parts, err := Render(ctx, fset, d, RenderOptions{
-		FileLinkFunc:     func(string) string { return "file" },
-		SourceLinkFunc:   func(ast.Node) string { return "src" },
-		SinceVersionFunc: func(string) string { return "" },
-	})
+	parts, err := Render(ctx, fset, d, testRenderOptions)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -108,10 +110,7 @@ func TestExampleRender(t *testing.T) {
 	ctx := context.Background()
 	fset, d := mustLoadPackage("example_test")
 
-	parts, err := Render(ctx, fset, d, RenderOptions{
-		FileLinkFunc:   func(string) string { return "file" },
-		SourceLinkFunc: func(ast.Node) string { return "src" },
-	})
+	parts, err := Render(ctx, fset, d, testRenderOptions)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -354,6 +353,33 @@ func TestVersionedPkgPath(t *testing.T) {
 	}
 }
 
+func TestDeprecated(t *testing.T) {
+	LoadTemplates(templateSource)
+	ctx := context.Background()
+	fset, d := mustLoadPackage("deprecated")
+	parts, err := Render(ctx, fset, d, testRenderOptions)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// In package deprecated, all non-deprecated symbols begin with "Good" and
+	// all deprecated ones begin with "Bad".
+	// There is one const, var, func and type of each.
+
+	// The outline only has functions and types, so we should see two "Good"s and no "Bad"s.
+	outlineString := parts.Outline.String()
+	for _, want := range []string{"GoodF()", "type GoodT", "GoodM", "NewGoodTGood()"} {
+		if !strings.Contains(outlineString, want) {
+			t.Errorf("outline does not have %q but should", want)
+		}
+	}
+	for _, notWant := range []string{"BadF()", "type BadT", "BadM()", "NewGoodTBad()"} {
+		if strings.Contains(outlineString, notWant) {
+			t.Errorf("outline has %q but shouldn't", notWant)
+		}
+	}
+
+}
+
 func testDuplicateIDs(t *testing.T, htmlDoc *html.Node) {
 	idCounts := map[string]int{}
 	walk(htmlDoc, func(n *html.Node) {

diff --git a/internal/godoc/dochtml/testdata/deprecated.go b/internal/godoc/dochtml/testdata/deprecated.go
@@ -0,0 +1,43 @@
+// Copyright 2021 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.
+
+// Package deprecated has some deprecated symbols.
+package deprecated
+
+const GoodC = 1
+
+// BadC is bad.
+// Deprecated: use GoodC.
+const BadC = 2
+
+var GoodV = 1
+
+var BadV = 2 // Deprecated: use GoodV.
+
+func GoodF() {}
+
+/*
+   BadF is bad.
+   Deprecated: use GoodF.
+*/
+func BadF() {}
+
+type GoodT int
+
+// BadT is bad.
+// Deprecated: use GoodT.
+// Don't use this.
+type BadT int
+
+func NewGoodTGood() GoodT {}
+
+// NewGoodTBad is bad.
+// Deprecated: use NewGoodTGood.
+func NewGoodTBad() GoodT {}
+
+func (GoodT) GoodM() {}
+
+// BadM is bad.
+// Deprecated: use GoodM.
+func (GoodT) BadM() {}
diff --git a/internal/godoc/internal/doc/doc.go b/internal/godoc/internal/doc/doc.go
@@ -49,9 +49,10 @@ type Package struct {
 
 // Value is the documentation for a (possibly grouped) var or const declaration.
 type Value struct {
-	Doc   string
-	Names []string // var or const names in declaration order
-	Decl  *ast.GenDecl
+	Doc          string
+	Names        []string // var or const names in declaration order
+	Decl         *ast.GenDecl
+	IsDeprecated bool
 
 	order int
 }
@@ -72,6 +73,8 @@ type Type struct {
 	// this type. Examples are extracted from _test.go files
 	// provided to NewFromFiles.
 	Examples []*Example
+
+	IsDeprecated bool
 }
 
 // Func is the documentation for a func declaration.
@@ -90,6 +93,8 @@ type Func struct {
 	// function or method. Examples are extracted from _test.go files
 	// provided to NewFromFiles.
 	Examples []*Example
+
+	IsDeprecated bool
 }
 
 // A Note represents a marked comment starting with "MARKER(uid): note body".

diff --git a/internal/godoc/internal/doc/reader.go b/internal/godoc/internal/doc/reader.go
@@ -60,12 +60,14 @@ func (mset methodSet) set(f *ast.FuncDecl, preserveAST bool) {
 		}
 		recv = recvString(typ)
 	}
+	text := f.Doc.Text()
 	mset[name] = &Func{
-		Doc:  f.Doc.Text(),
-		Name: name,
-		Decl: f,
-		Recv: recv,
-		Orig: recv,
+		Doc:          text,
+		IsDeprecated: isDeprecated(text),
+		Name:         name,
+		Decl:         f,
+		Recv:         recv,
+		Orig:         recv,
 	}
 	if !preserveAST {
 		f.Doc = nil // doc consumed - remove from AST
@@ -297,11 +299,13 @@ func (r *reader) readValue(decl *ast.GenDecl) {
 		}
 	}
 
+	text := decl.Doc.Text()
 	*values = append(*values, &Value{
-		Doc:   decl.Doc.Text(),
-		Names: specNames(decl.Specs),
-		Decl:  decl,
-		order: r.order,
+		Doc:          text,
+		IsDeprecated: isDeprecated(text),
+		Names:        specNames(decl.Specs),
+		Decl:         decl,
+		order:        r.order,
 	})
 	if r.mode&PreserveAST == 0 {
 		decl.Doc = nil // doc consumed - remove from AST
@@ -798,13 +802,14 @@ func sortedTypes(m map[string]*namedType, allMethods bool) []*Type {
 	i := 0
 	for _, t := range m {
 		list[i] = &Type{
-			Doc:     t.doc,
-			Name:    t.name,
-			Decl:    t.decl,
-			Consts:  sortedValues(t.values, token.CONST),
-			Vars:    sortedValues(t.values, token.VAR),
-			Funcs:   sortedFuncs(t.funcs, true),
-			Methods: sortedFuncs(t.methods, allMethods),
+			Doc:          t.doc,
+			IsDeprecated: isDeprecated(t.doc),
+			Name:         t.name,
+			Decl:         t.decl,
+			Consts:       sortedValues(t.values, token.CONST),
+			Vars:         sortedValues(t.values, token.VAR),
+			Funcs:        sortedFuncs(t.funcs, true),
+			Methods:      sortedFuncs(t.methods, allMethods),
 		}
 		i++
 	}
@@ -860,6 +865,13 @@ func noteBodies(notes []*Note) []string {
 	return list
 }
 
+var deprecatedRx = regexp.MustCompile(`(^|\n)\s*Deprecated:`) // "Deprecated:" at the start of a line.
+
+// isDeprecated reports whether the string has a "Deprecated" line.
+func isDeprecated(s string) bool {
+	return deprecatedRx.MatchString(s)
+}
+
 // ----------------------------------------------------------------------------
 // Predeclared identifiers
 

diff --git a/internal/godoc/internal/doc/reader_test.go b/internal/godoc/internal/doc/reader_test.go
@@ -0,0 +1,27 @@
+// Copyright 2021 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.
+
+package doc
+
+import (
+	"testing"
+)
+
+func TestIsDeprecated(t *testing.T) {
+	for _, test := range []struct {
+		text string
+		want bool
+	}{
+		{"A comment", false},
+		{"Deprecated: foo", true},
+		{" A comment\n   Deprecated: foo", true},
+		{"This is\n Deprecated.", false},
+		{"line 1\nDeprecated:\nline 2\n", true},
+	} {
+		got := isDeprecated(test.text)
+		if got != test.want {
+			t.Errorf("%q: got %t, want %t", test.text, got, test.want)
+		}
+	}
+}