net/http: clarify docs of ParseForm and mention ParseForm in docs for FormValue

net/http: clarify docs of ParseForm and mention ParseForm in docs for FormValue
while we're at it, also fix a return value stutter in ParseForm.

[minux1, 2012-11-20 09:43:29]

Hello golang-dev@googlegroups.com (cc: golang-dev@googlegroups.com),

I'd like you to review this change to
https://code.google.com/p/go

[bradfitz, 2012-11-20 16:12:32]

Avoid the word "you".  Notice that the current docs never use it:
http://tip.golang.org/pkg/net/http/

On Tue, Nov 20, 2012 at 1:43 AM, <minux.ma@gmail.com> wrote:

> Reviewers: golang-dev_googlegroups.com,
>
> Message:
> Hello golang-dev@googlegroups.com (cc: golang-dev@googlegroups.com),
>
> I'd like you to review this change to
> https://code.google.com/p/go
>
>
> Description:
> net/http: mention ParseForm and Form in docs for (*Request).FormValue
>
> Please review this at
http://codereview.appspot.com/**6847074/<http://codereview.appspot.com/6847074/>
>
> Affected files:
>   M src/pkg/net/http/request.go
>
>
> Index: src/pkg/net/http/request.go
> ==============================**==============================**=======
> --- a/src/pkg/net/http/request.go
> +++ b/src/pkg/net/http/request.go
> @@ -728,6 +728,8 @@
>  // FormValue returns the first value for the named component of the query.
>  // POST and PUT body parameters take precedence over URL query string
> values.
>  // FormValue calls ParseMultipartForm and ParseForm if necessary.
> +// If you want multiple values of the same key, invoke r.ParseForm() and
> +// use r.Form directly.
>  func (r *Request) FormValue(key string) string {
>         if r.Form == nil {
>                 r.ParseMultipartForm(**defaultMaxMemory)
>
>
>

[minux1, 2012-11-20 18:03:40]

Hello golang-dev@googlegroups.com, bradfitz@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[bradfitz, 2012-11-20 18:32:37]

https://codereview.appspot.com/6847074/diff/7001/src/pkg/net/http/request.go
File src/pkg/net/http/request.go (right):

https://codereview.appspot.com/6847074/diff/7001/src/pkg/net/http/request.go#...
src/pkg/net/http/request.go:731: // If multiple values of the same key is
needed, invoke r.ParseForm() and
s/is/are/ and drop the parens on ParseForm.  Actually, I'd drop everything from
"and ..." and move that to the docs of ParseForm where it's currently missing.

So this is just:

// If multiple values of the same key are needed, use ParseForm.

Or, dropping the passive voice:

// To access multiple values of the same key use ParseForm.

I'm not the wordsmith, though.  That should be closer, though.  Rob or Russ
might suggest further changes.

[minux1, 2012-11-21 08:09:57]

PTAL.

[bradfitz, 2012-11-22 15:30:45]

https://codereview.appspot.com/6847074/diff/11001/src/pkg/net/http/request.go
File src/pkg/net/http/request.go (right):

https://codereview.appspot.com/6847074/diff/11001/src/pkg/net/http/request.go...
src/pkg/net/http/request.go:653: // After calling this, use Form field of r to
access multiple values of the
Also mention PostForm.  I would just tell them what the function does and not
explain how to solve every problem.

They can learn read the definition of r.Form and see that it's multi-valued, so
need to say "to access multiple values".  Just describe what is populated in
what cases.

https://codereview.appspot.com/6847074/diff/11001/src/pkg/net/http/request.go...
src/pkg/net/http/request.go:658: func (r *Request) ParseForm() (err error) {
can you fix this return value stutter while you're at it?  Just "error", not
"(err error)".

[minux1, 2012-11-23 11:54:27]

PTAL.

On 2012/11/22 15:30:45, bradfitz wrote:
>
https://codereview.appspot.com/6847074/diff/11001/src/pkg/net/http/request.go...
> src/pkg/net/http/request.go:653: // After calling this, use Form field of r to
> access multiple values of the
> Also mention PostForm.  I would just tell them what the function does and not
> explain how to solve every problem.
> 
> They can learn read the definition of r.Form and see that it's multi-valued,
so
> need to say "to access multiple values".  Just describe what is populated in
> what cases.
I see. I partly rewrite docs for ParseForm, hope the new docs makes things
clear.
>
https://codereview.appspot.com/6847074/diff/11001/src/pkg/net/http/request.go...
> src/pkg/net/http/request.go:658: func (r *Request) ParseForm() (err error) {
> can you fix this return value stutter while you're at it?  Just "error", not
> "(err error)".
Done.

[bradfitz, 2012-11-26 03:53:54]

LGTM after removing commas

https://codereview.appspot.com/6847074/diff/3/src/pkg/net/http/request.go
File src/pkg/net/http/request.go (right):

https://codereview.appspot.com/6847074/diff/3/src/pkg/net/http/request.go#new...
src/pkg/net/http/request.go:646: // ParseForm parses the raw query from the URL,
and updates r.Form.
drop the comma

https://codereview.appspot.com/6847074/diff/3/src/pkg/net/http/request.go#new...
src/pkg/net/http/request.go:648: // For POST or PUT requests, it also parses the
request body as a form, and
drop the comma

[minux1, 2012-11-26 12:03:52]

*** Submitted as http://code.google.com/p/go/source/detail?r=448fb06d74ee ***

net/http: clarify docs of ParseForm and mention ParseForm in docs for FormValue
while we're at it, also fix a return value stutter in ParseForm.

R=bradfitz
CC=golang-dev
http://codereview.appspot.com/6847074