proposal: go/doc: deprecate New

[mateusz834]

Proposal Details

In the go/doc there is a function that accepts a *ast.Package, called New. We already have an alternative that work with ordinary *ast.Files, NewFromFiles. So i think that we should deprecate it in favour of NewFromFiles.

Related: #71122, #73088, #7124

CC @adonovan @griesemer

[mateusz834]

New docs already suggest using NewFromFiles

go/src/go/doc/doc.go

Lines 119 to 121 in 26fdb07

	// To have the [Examples] fields populated, use [NewFromFiles] and include
	// the package's _test.go files.
	func New(pkg *ast.Package, importPath string, mode Mode) *Package {

[mateusz834]

Also: #66290 (might be a blocker for this)

https://github.com/golang/tools/blob/a857356d5cc56c01228c895b060f0594e537b4eb/gopls/internal/golang/pkgdoc.go#L279-L285

[gabyhelp]

Related Code Changes

• doc/go1.14: mention go/doc.NewFromFiles and associated new data fields

Related Documentation

• Package doc > type Package ¶ > func New ¶

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}