diff --git a/internal/godocfx/godocfx_test.go b/internal/godocfx/godocfx_test.go index 4b92a84a4d2..d91c32ffcb2 100644 --- a/internal/godocfx/godocfx_test.go +++ b/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) + } + } +} diff --git a/internal/godocfx/parse.go b/internal/godocfx/parse.go index e46677c2c68..179f82d406b 100644 --- a/internal/godocfx/parse.go +++ b/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 diff --git a/internal/godocfx/testdata/golden/index.yml b/internal/godocfx/testdata/golden/index.yml index 8d127e93adf..99a93e765d5 100644 --- a/internal/godocfx/testdata/golden/index.yml +++ b/internal/godocfx/testdata/golden/index.yml @@ -2699,6 +2699,7 @@ items: syntax: content: func (r *Reader) CacheControl() string + status: deprecated - uid: cloud.google.com/go/storage.Reader.Close name: | func (*Reader) Close @@ -2727,6 +2728,7 @@ items: syntax: content: func (r *Reader) ContentEncoding() string + status: deprecated - uid: cloud.google.com/go/storage.Reader.ContentType name: | func (*Reader) ContentType @@ -2742,6 +2744,7 @@ items: syntax: content: func (r *Reader) ContentType() string + status: deprecated - uid: cloud.google.com/go/storage.Reader.LastModified name: | func (*Reader) LastModified @@ -2758,6 +2761,7 @@ items: content: func (r *Reader) LastModified() (time.Time, error) + status: deprecated - uid: cloud.google.com/go/storage.Reader.Read name: | func (*Reader) Read @@ -2800,6 +2804,7 @@ items: syntax: content: func (r *Reader) Size() int64 + status: deprecated - uid: cloud.google.com/go/storage.ReaderObjectAttrs name: ReaderObjectAttrs id: ReaderObjectAttrs @@ -3108,6 +3113,7 @@ items: syntax: content: func (w *Writer) CloseWithError(err error) error + status: deprecated - uid: cloud.google.com/go/storage.Writer.Write name: | func (*Writer) Write