code review 5312052: http: add package comment

http: add package comment

Fixes issue 2378

[bradfitz, 2011-10-24 20:02:45]

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

I'd like you to review this change to
https://go.googlecode.com/hg/

[rsc, 2011-10-24 20:17:09]

LGTM

Very nice.
Can shorten the text a bit.

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go
File src/pkg/http/doc.go (right):

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode8
src/pkg/http/doc.go:8: To use the HTTP client, use one of the high-level
functions Get, Head,
Get, Head, Post, and PostForm make HTTP requests:

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode11
src/pkg/http/doc.go:11: resp, err := http.Get("http://example.com/")
Please indent with tabs, so that it's easy to pick up and
drop into programs.

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode18
src/pkg/http/doc.go:18: The Response.Body should be closed after it's been read.
Client code
The client must close the response body when finished with it:

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode29
src/pkg/http/doc.go:29: A lower-level interface to the HTTP client is available
by creating your
For control over HTTP client headers or TLS settings, create a Transport and
Client:

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode41
src/pkg/http/doc.go:41: To use the HTTP server, use ListenAndServe with an
address and
ListenAndServe starts an HTTP server with a given address and handler.
The handler is usually nil, which means to use DefaultServeMux.
Handle and HandleFunc add handlers to DefaultServeMux:

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode43
src/pkg/http/doc.go:43: DefaultServeMux is used.  The functions Handle and
HandleFunc register
s/The functions //

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode55
src/pkg/http/doc.go:55: More control over the server's behavior is available by
creating a
For control over timeouts and other settings, create a Server:

[bradfitz, 2011-10-24 20:49:03]

PTAL

Re-uploaded.

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go
File src/pkg/http/doc.go (right):

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode8
src/pkg/http/doc.go:8: To use the HTTP client, use one of the high-level
functions Get, Head,
On 2011/10/24 20:17:09, rsc wrote:
> Get, Head, Post, and PostForm make HTTP requests:

Done.

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode11
src/pkg/http/doc.go:11: resp, err := http.Get("http://example.com/")
On 2011/10/24 20:17:09, rsc wrote:
> Please indent with tabs, so that it's easy to pick up and
> drop into programs.

Done.

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode18
src/pkg/http/doc.go:18: The Response.Body should be closed after it's been read.
Client code
On 2011/10/24 20:17:09, rsc wrote:
> The client must close the response body when finished with it:

Done.

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode29
src/pkg/http/doc.go:29: A lower-level interface to the HTTP client is available
by creating your
On 2011/10/24 20:17:09, rsc wrote:
> For control over HTTP client headers or TLS settings, create a Transport and
> Client:

This was the only feedback that felt awkward, implying you had to create both. 
It also highlighted that I didn't have a custom header example (showing Do,
which comes up frequently enough on the list).

I broke it into a custom Client and custom Transport section.

I also documented that it's thread-safe.

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode41
src/pkg/http/doc.go:41: To use the HTTP server, use ListenAndServe with an
address and
On 2011/10/24 20:17:09, rsc wrote:
> ListenAndServe starts an HTTP server with a given address and handler.
> The handler is usually nil, which means to use DefaultServeMux.
> Handle and HandleFunc add handlers to DefaultServeMux:

Done.

http://codereview.appspot.com/5312052/diff/2001/src/pkg/http/doc.go#newcode43
src/pkg/http/doc.go:43: DefaultServeMux is used.  The functions Handle and
HandleFunc register
On 2011/10/24 20:17:09, rsc wrote:
> s/The functions //

Done.

[rsc, 2011-10-24 20:57:49]

LGTM

Fantastic.

[bradfitz, 2011-10-24 20:59:38]

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

http: add package comment

Fixes issue 2378

R=rsc
CC=golang-dev
http://codereview.appspot.com/5312052