net/http: Redirect documentation refers to non-existent url identifier (it was renamed)

[dmitshur]

A very cool new package url was recently added to the Go standard library, see commit 1d8f822. To avoid a name collision, the existing url parameter of http.Redirect function was renamed to urlStr.

 // Redirect replies to the request with a redirect to url,
 // which may be a path relative to the request path.
-func Redirect(w ResponseWriter, r *Request, url string, code int) {
+func Redirect(w ResponseWriter, r *Request, urlStr string, code int) {

However, it looks like you forgot to update the documentation accordingly. It should be changed as follows:

-// Redirect replies to the request with a redirect to url,
+// Redirect replies to the request with a redirect to urlStr,
 // which may be a path relative to the request path.

Otherwise, it's not clear which url is being referred to. One may inadvertently misinterpret it to mean r.URL, which is not the case.

(I was going through my open tabs, and noticed I forgot to hit submit on this one. Better late than never. 🤷‍♂️)

[gopherbot]

CL https://golang.org/cl/49712 mentions this issue.

[dmitshur]

CL 49712 implements the fix and is valid.

However, it got me thinking. Perhaps a better, alternative fix should be considered.

Go favors clarity of API documentation over implementation difficulties. See https://golang.org/s/style#named-result-parameters:

Clarity of docs is always more important than saving a line or two in your function.

The name urlStr was obviously chosen over url in response to the identifier collision (edit: see comment by @rsc at https://codereview.appspot.com/4893043#msg4). It is possible to avoid the identifier collision in an alternative way, by renaming the imported net/url package to something else (for example, import urlpkg "net/url"), then the documentation of net/http package can be more clear.

I think this would read better:

// Redirect replies to the request with a redirect to url,
// which may be a path relative to the request path.
// ...
func Redirect(w ResponseWriter, r *Request, url string, code int) {

Would it not? It's clear that url is a string from the signature, naming it urlStr does not improve external documentation clarity.

Renaming url import inside net/http may not be nice, but it only has to be in one .go file (where Redirect is defined), and it's an internal implementation detail.

It may not be worth it doing this, but I thought it was worth mentioning so it could be considered. /cc @bradfitz @ianlancetaylor @robpike

[dmitshur]

(The bot isn't mentioning this, likely because it's a closed/frozen issue.)

CL 49930 mentions this issue.

CL 202482 (from 2019) also mentioned this issue.