Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
tbpg committed Aug 2, 2021
1 parent e5a891a commit d571c6f
Show file tree
Hide file tree
Showing 3 changed files with 51 additions and 0 deletions.
26 changes: 26 additions & 0 deletions internal/godocfx/godocfx_test.go
Expand Up @@ -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)
}
}
}
19 changes: 19 additions & 0 deletions internal/godocfx/parse.go
Expand Up @@ -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) {
Expand Down Expand Up @@ -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 {
Expand All @@ -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 {
Expand All @@ -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.
Expand All @@ -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 {
Expand All @@ -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),
})
}

Expand All @@ -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 {
Expand All @@ -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),
})
}
}
Expand All @@ -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),
})
}
}
Expand All @@ -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
Expand Down
6 changes: 6 additions & 0 deletions internal/godocfx/testdata/golden/index.yml
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit d571c6f

Please sign in to comment.