x/tools/cmd/godoc: hide deprecated things by default

[bradfitz]

Summary

https://golang.org/pkg/net/http/httputil/ has some garbage I'd like to hide. I'd like to hide everything about ClientConn and ServerConn

Background:

Before Go 1, we renamed the http package to net/http and in the process deleted some junk, and moved other junk to net/http/httputil, thinking that people might still need it. This was all pre-Go 1 when the APIs were changing daily, weekly, monthly. But we were trying to be nice anyway.

Turns out nobody needed that junk, though, even then, and not today:

https://github.com/search?utf8=%E2%9C%93&q=httputil.ClientConn&ref=simplesearch
https://github.com/search?utf8=%E2%9C%93&q=httputil.NewClientConn&type=Repositories&ref=searchresults
https://github.com/search?utf8=%E2%9C%93&q=httputil.ServerConn&type=Repositories&ref=searchresults
https://github.com/search?utf8=%E2%9C%93&q=httputil.NewServerConn&type=Repositories&ref=searchresults

Zero results.

I updated the docs some time ago:

https://golang.org/pkg/net/http/httputil/#ClientConn

... says simply:

ClientConn is an artifact of Go's early HTTP implementation. It is low-level, old, and unused by Go's current HTTP stack. We should have deleted it before Go 1.

Deprecated: Use Client or Transport in package net/http instead.

There are a couple good bits in there, though. ReverseProxy is very widely used, and the Dump* functions are often used in debugging.

Plan

Let godoc have configuration on public symbols to treat as if they were private. And then use that configuration for godoc.org to hide that junk, without deleting them from the package, so we don't violate the Go 1 compatibility promise. Think of this as a very strong form of deprecation.

If users really want to see it, they can use https://golang.org/pkg/net/http/httputil/?m=all to see all the junk.

FAQ

But Brad, this is a very slippery slope. What will we hide next?
Good question. There might be more to hide.

But why?
Because httputil looks embarrassing, and it looking like a trash heap prevents us from non-embarrassingly adding anything else to it. Let's clean up the house before we invite guests over.

/cc @griesemer @adg @broady @quentinmit @minux @campoy

[jimmyfrasche]

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]

What about we make godoc hide deprecated definition by default? And like Google search suppresses similar results, it could add a line at the bottom: Several deprecated definitions have been suppressed, if you want, use <a href="?m=includedeprecated">this link</a> to view them. Or we can add a new foldable category "Deprecated" that is hidden by default. We already formalized a way to do proper deprecation, I think this is the logical next step.

[bradfitz]

@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.

[adg]

SGTM

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

[j7b]

👎 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.

[broady]

+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.

[minux]

Hiding deprecated stuff doesn't mean removing them. I think we can use JavaScript to hide them so that an explicit link golang.org/pkg/net/http/httputil/#ClientConn will still show the docs (without manually toggling the show deprecated stuff setting).

[dsnet]

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.

[bradfitz]

@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.

[dsnet]

@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).