I'm all for cleaning up the documentation, but I don't like doing so by blacklist. What if godoc sorted items marked Deprecated below everything else and collapsed Deprecated items by default?

That would work with the (semi?) standard deprecation warnings for everyone without a special case for officially super-deprecated items. It wouldn't be totally hidden but it would be less messy, clearer that stuff is deprecated at a glance in general, and not too difficult for someone to look up deprecated docs if needed.

Something like:

func DumpRequest(req *http.Request, body bool) ([]byte, error)
func DumpRequestOut(req *http.Request, body bool) ([]byte, error)
func DumpResponse(resp *http.Response, body bool) ([]byte, error)
func NewChunkedReader(r io.Reader) io.Reader
func NewChunkedWriter(w io.Writer) io.WriteCloser
type BufferPool
type ReverseProxy
    func NewSingleHostReverseProxy(target *url.URL) *ReverseProxy
    func (p *ReverseProxy) ServeHTTP(rw http.ResponseWriter, req *http.Request)

type ClientConn Deprecated (click to expand arrow icon thingy)
type ServerConn  Deprecated (click to expand arrow icon thingy)

where the {Client,Server}Conn's full documentation is at the bottom of the page, similarly collapsed.

@minux, SGTM. Hiding all deprecated things works for me with a mode to include them. Or have them simply be JavaScript-hidden is fine too, similar to Examples.

SGTM

Good idea. Present the current docs by default, but still make legacy docs available to those who need them.

👎 because the "zero results" is misleading, a quick search finds examples in the wild like https://github.com/samalba/skyproxy/blob/master/client/client.go and there's also cases where ClientConn is less painful than working around the net/http interfaces. Giving deprecated stuff a separate section is probably reasonable but hiding it is at the very least also misleading.

+1 for telling people that there are N things hidden. If they choose to "show all", let's also mark the deprecated stuff with an icon and group them together at the bottom.

What is the string that godoc will look for? Is it Deprecated: at the beginning of a comment line? I think I've also seen DEPRECATED used.

I have a minor concern with simply hiding deprecated items. If I'm reviewing some code that uses a deprecated feature that I'm unfamiliar with and then go to the godoc of the package, I'll be a little confused when cntrl-f doesn't show the deprecated feature in question. Remembering to show deprecated features is probably not my first thought. Is it possible for cntrl-f to search through (and show) javascript hidden elements?

However, I strongly believe that we should display deprecated features differently somehow in godoc.

Edit: Just a thought, maybe hide deprecated types, methods, and functions from the index? but still show them in package documentation? It's inconsistent, so I'm on the fence about this idea.

@dsnet, to address your Ctrl-F concern, we can make the JavaScript put at the bottom of the page:

Hiding 5 deprecated things: Foo, Bar, Type, Type.Method, Baz.

And each could be a link to #Foo, #Type.Method, etc, which like @minux said would open up the hidden element.

@broady

What is the string that godoc will look for? Is it Deprecated: at the beginning of a comment line? I think I've also seen DEPRECATED used.

It seems that #10909 settled on Deprecated: as the convention. There's even some discussion on that issue about altering godoc to handle that string specially, but obviously we didn't really move forward with that work (till now).

The plan:

• Deprecated items are not listed in the index
• A separate short list of deprecated symbols is presented after the index
• Deprecated symbols are documented in a separate section, below the other code
• The deprecated symbol docs are collapsed by default, as with examples
• A direct link to a deprecated symbol shows the docs already expanded, as with examples

The go doc command also needs to address this, consistently with godoc. That's a separate issue.

Just wondering. How do you plan on handling deprecated fields in structs (e.g., zip.FileHeader.CompressedSize)?

We'll probably punt on it. I don't see an elegant way of dealing with it.

On 26 October 2016 at 07:36, Joe Tsai notifications@github.com wrote:

Just wondering. How do you plan on handling deprecated fields in structs
(e.g., zip.FileHeader.CompressedSize
https://golang.org/pkg/archive/zip/#FileHeader)?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#17056 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AIDilZ8x6KzPBEvawTEs4A63fliYPeDsks5q3mhkgaJpZM4J51O6
.

Maybe just use strike out text on the struct fields? Apologies if this was already discussed or declined.

+1 to strike through. There are already similar issues filed against godoc.org and golint by the way.

golang/lint#238
golang/gddo#456

Strike-through seems too aggressive or at least too unreadable. I'd do a JS expando before I did strike-through.

As @adg pointed out, there seems to be no elegant way of handling deprecated fields in structs. I totally agree with using "JS expando" for all other elements. Strike-through is just a possible solution for struct fields.

Change https://golang.org/cl/70110 mentions this issue: encoding/json: use Deprecated markers

As part of my work on #18342, I'm close to a working prototype of this. I'm going to self-assign this

@dmitshur is this on the roadmap for http://pkg.go.dev/ ?

I think it should absolutely be considered.

/cc @julieqiu

+1 - filed a separate issue (#40850)

Change https://golang.org/cl/315509 mentions this issue: content/static/html/doc: group type and sub-items

cmd/godoc is essentially in maintenance mode, so we can close this issue.