feat(internal/godocfx): mark status of deprecated items (#4525)

A separate PR will update the template to use this new field.

A future PR here may include a `status` for the overall package and in the TOC.

Author: tbpg

internal/godocfx/godocfx_test.go

@@ -254,3 +254,29 @@ stem: "/appengine/docs/standard/go/reference/services/bundled"
 		}
 	}
 }
+
+func TestGetStatus(t *testing.T) {
+	tests := []struct {
+		doc  string
+		want string
+	}{
+		{
+			doc: `Size returns the size of the object in bytes.
+The returned value is always the same and is not affected by
+calls to Read or Close.
+
+Deprecated: use Reader.Attrs.Size.`,
+			want: "deprecated",
+		},
+		{
+			doc:  `This will never be deprecated!`,
+			want: "",
+		},
+	}
+
+	for _, test := range tests {
+		if got := getStatus(test.doc); got != test.want {
+			t.Errorf("getStatus(%v) got %q, want %q", test.doc, got, test.want)
+		}
+	}
+}

internal/godocfx/parse.go

@@ -93,6 +93,7 @@ type item struct {
 	Examples []example `yaml:"codeexamples,omitempty"`
 	Children []child   `yaml:"children,omitempty"`
 	AltLink  string    `yaml:"alt_link,omitempty"`
+	Status   string    `yaml:"status,omitempty"`
 }
 
 func (p *page) addItem(i *item) {
@@ -186,6 +187,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string, filter [
 				Summary: c.Doc,
 				Langs:   onlyGo,
 				Syntax:  syntax{Content: pkgsite.PrintType(pi.Fset, c.Decl, link.toURL, topLevelDecls)},
+				Status:  getStatus(c.Doc),
 			})
 		}
 		for _, v := range pi.Doc.Vars {
@@ -202,6 +204,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string, filter [
 				Summary: v.Doc,
 				Langs:   onlyGo,
 				Syntax:  syntax{Content: pkgsite.PrintType(pi.Fset, v.Decl, link.toURL, topLevelDecls)},
+				Status:  getStatus(v.Doc),
 			})
 		}
 		for _, t := range pi.Doc.Types {
@@ -217,6 +220,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string, filter [
 				Langs:    onlyGo,
 				Syntax:   syntax{Content: pkgsite.PrintType(pi.Fset, t.Decl, link.toURL, topLevelDecls)},
 				Examples: processExamples(t.Examples, pi.Fset),
+				Status:   getStatus(t.Doc),
 			}
 			// Note: items are added as page.Children, rather than
 			// typeItem.Children, as a workaround for the DocFX template.
@@ -235,6 +239,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string, filter [
 					Summary: c.Doc,
 					Langs:   onlyGo,
 					Syntax:  syntax{Content: pkgsite.PrintType(pi.Fset, c.Decl, link.toURL, topLevelDecls)},
+					Status:  getStatus(c.Doc),
 				})
 			}
 			for _, v := range t.Vars {
@@ -251,6 +256,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string, filter [
 					Summary: v.Doc,
 					Langs:   onlyGo,
 					Syntax:  syntax{Content: pkgsite.PrintType(pi.Fset, v.Decl, link.toURL, topLevelDecls)},
+					Status:  getStatus(v.Doc),
 				})
 			}
 
@@ -267,6 +273,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string, filter [
 					Langs:    onlyGo,
 					Syntax:   syntax{Content: pkgsite.Synopsis(pi.Fset, fn.Decl, link.linkify)},
 					Examples: processExamples(fn.Examples, pi.Fset),
+					Status:   getStatus(fn.Doc),
 				})
 			}
 			for _, fn := range t.Methods {
@@ -282,6 +289,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string, filter [
 					Langs:    onlyGo,
 					Syntax:   syntax{Content: pkgsite.Synopsis(pi.Fset, fn.Decl, link.linkify)},
 					Examples: processExamples(fn.Examples, pi.Fset),
+					Status:   getStatus(fn.Doc),
 				})
 			}
 		}
@@ -298,6 +306,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string, filter [
 				Langs:    onlyGo,
 				Syntax:   syntax{Content: pkgsite.Synopsis(pi.Fset, fn.Decl, link.linkify)},
 				Examples: processExamples(fn.Examples, pi.Fset),
+				Status:   getStatus(fn.Doc),
 			})
 		}
 	}
@@ -310,6 +319,16 @@ func parse(glob string, workingDir string, optionalExtraFiles []string, filter [
 	}, nil
 }
 
+// getStatus returns a possibly empty status string for the given
+// docs.
+func getStatus(doc string) string {
+	deprecated := "\nDeprecated:"
+	if strings.Contains(doc, deprecated) {
+		return "deprecated"
+	}
+	return ""
+}
+
 type linker struct {
 	// imports is a map from local package name to import path.
 	// Behavior is undefined when a single import has different names in

internal/godocfx/testdata/golden/index.yml

@@ -2699,6 +2699,7 @@ items:
   syntax:
     content: func (r *<a href="#cloud_google_com_go_storage_Reader">Reader</a>) CacheControl()
       <a href="https://pkg.go.dev/builtin#string">string</a>
+  status: deprecated
 - uid: cloud.google.com/go/storage.Reader.Close
   name: |
     func (*Reader) Close
@@ -2727,6 +2728,7 @@ items:
   syntax:
     content: func (r *<a href="#cloud_google_com_go_storage_Reader">Reader</a>) ContentEncoding()
       <a href="https://pkg.go.dev/builtin#string">string</a>
+  status: deprecated
 - uid: cloud.google.com/go/storage.Reader.ContentType
   name: |
     func (*Reader) ContentType
@@ -2742,6 +2744,7 @@ items:
   syntax:
     content: func (r *<a href="#cloud_google_com_go_storage_Reader">Reader</a>) ContentType()
       <a href="https://pkg.go.dev/builtin#string">string</a>
+  status: deprecated
 - uid: cloud.google.com/go/storage.Reader.LastModified
   name: |
     func (*Reader) LastModified
@@ -2758,6 +2761,7 @@ items:
     content: func (r *<a href="#cloud_google_com_go_storage_Reader">Reader</a>) LastModified()
       (<a href="https://pkg.go.dev/time">time</a>.<a href="https://pkg.go.dev/time#Time">Time</a>,
       <a href="https://pkg.go.dev/builtin#error">error</a>)
+  status: deprecated
 - uid: cloud.google.com/go/storage.Reader.Read
   name: |
     func (*Reader) Read
@@ -2800,6 +2804,7 @@ items:
   syntax:
     content: func (r *<a href="#cloud_google_com_go_storage_Reader">Reader</a>) Size()
       <a href="https://pkg.go.dev/builtin#int64">int64</a>
+  status: deprecated
 - uid: cloud.google.com/go/storage.ReaderObjectAttrs
   name: ReaderObjectAttrs
   id: ReaderObjectAttrs
@@ -3108,6 +3113,7 @@ items:
   syntax:
     content: func (w *<a href="#cloud_google_com_go_storage_Writer">Writer</a>) CloseWithError(err
       <a href="https://pkg.go.dev/builtin#error">error</a>) <a href="https://pkg.go.dev/builtin#error">error</a>
+  status: deprecated
 - uid: cloud.google.com/go/storage.Writer.Write
   name: |
     func (*Writer) Write