net/http: (*Request) ParseForm: document the error condition

[kevinburke]

The current documentation for ParseForm doesn't describe when an error can be returned:

ParseForm populates r.Form and r.PostForm.

For all requests, ParseForm parses the raw query from the URL and updates r.Form.

For POST, PUT, and PATCH requests, it also parses the request body as a form and puts the results into both r.PostForm and r.Form. Request body parameters take precedence over URL query string values in r.Form.

For other HTTP methods, or when the Content-Type is not application/x-www-form-urlencoded, the request Body is not read, and r.PostForm is initialized to a non-nil, empty value.

If the request Body's size has not already been limited by MaxBytesReader, the size is capped at 10MB.

ParseMultipartForm calls ParseForm automatically. ParseForm is idempotent.

https://godoc.org/net/http#Request.ParseForm

[gopherbot]

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

[bradfitz]

Why is this API unique in its need to enumerate all the possible ways an error might be returned?

We don't do that elsewhere. If anything, we documented guaranteed error types or error values in places, but we rarely say "if X happens, an error will be returned"

[kevinburke]

I guess I was just sort of surprised that parsing could return an error and was wondering what condition the form parser could hit that would result in an error. In some cases oddities in parsing just result in setting the resulting url.Values to the empty string, or setting an empty value. It turns out one occurs if r.Body is nil or if a percent sign is not accompanied by a URL-unescapable value.

[dndungu]

The documentation was added. See https://github.com/golang/go/blob/master/src/net/http/request.go#L1220-L1237

cc @odeke-em