net/http: document, audit ProtocolError

[bradfitz]

https://golang.org/pkg/net/http/#ProtocolError is a bit of an oddball.

It's used a little:

$ git grep ProtocolError
httputil/persist.go:    ErrPersistEOF = &http.ProtocolError{ErrorString: "persistent connection closed"}
httputil/persist.go:    ErrClosed     = &http.ProtocolError{ErrorString: "connection closed by user"}
httputil/persist.go:    ErrPipeline   = &http.ProtocolError{ErrorString: "pipeline error"}
request.go:type ProtocolError struct {
request.go:func (err *ProtocolError) Error() string { return err.ErrorString }
request.go:     ErrHeaderTooLong        = &ProtocolError{"header too long"}
request.go:     ErrShortBody            = &ProtocolError{"entity body too short"}
request.go:     ErrNotSupported         = &ProtocolError{"feature not supported"}
request.go:     ErrUnexpectedTrailer    = &ProtocolError{"trailer header without chunked transfer encoding"}
request.go:     ErrMissingContentLength = &ProtocolError{"missing ContentLength in HEAD response"}
request.go:     ErrNotMultipart         = &ProtocolError{"request Content-Type isn't multipart/form-data"}
request.go:     ErrMissingBoundary      = &ProtocolError{"no multipart boundary param in Content-Type"}

Should it be used more? Are those error variables even used?

Check. If ProtocolError isn't consistently used and we don't want to make it so, document that it's not always used.

[gopherbot]

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