http: add package comment

Fixes #2378

R=rsc
CC=golang-dev
https://golang.org/cl/5312052

diff --git a/src/pkg/http/doc.go b/src/pkg/http/doc.go
new file mode 100644 (file)
index 0000000..0215893
--- /dev/null
+++ b/src/pkg/http/doc.go
@@ -0,0 +1,79 @@
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Package http provides HTTP client and server implementaions.
+
+Get, Head, Post, and PostForm make HTTP requests:
+
+       resp, err := http.Get("http://example.com/")
+       ...
+       resp, err := http.Post("http://example.com/upload", "image/jpeg", &buf)
+       ...
+       resp, err := http.PostForm("http://example.com/form",
+               url.Values{"key": {"Value"}, "id": {"123"}})
+
+The client must close the response body when finished with it:
+
+       resp, err := http.Get("http://example.com/")
+       if err != nil {
+               // handle error
+       }
+       defer resp.Body.Close()
+       body, err := ioutil.ReadAll(resp.Body)
+       // ...
+
+For control over HTTP client headers, redirect policy, and other
+settings, create a Client:
+
+       client := &http.Client{
+               CheckRedirect: redirectPolicyFunc,
+       }
+
+       resp, err := client.Get("http://example.com")
+       // ...
+
+       req := http.NewRequest("GET", "http://example.com", nil)
+       req.Header.Add("If-None-Match", `W/"wyzzy"`)
+       resp, err := client.Do(req)
+       // ...
+
+For control over proxies, TLS configuration, keep-alives,
+compression, and other settings, create a Transport:
+
+       tr := &http.Transport{
+               TLSClientConfig:    &tls.Config{RootCAs: pool},
+               DisableCompression: true,
+       }
+       client := &http.Client{Transport: tr}
+       resp, err := client.Get("https://example.com")
+
+Clients and Transports are safe for concurrent use by multiple
+goroutines and for efficiency should only be created once and re-used.
+
+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.Handle("/foo", fooHandler)
+
+       http.HandleFunc("/bar", func(w http.ResponseWriter, r *http.Request) {
+               fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.RawPath))
+       })
+
+       log.Fatal(http.ListenAndServe(":8080", nil))
+
+More control over the server's behavior is available by creating a
+custom Server:
+
+       s := &http.Server{
+               Addr:           ":8080",
+               Handler:        myHandler,
+               ReadTimeout:    10e9,
+               WriteTimeout:   10e9,
+               MaxHeaderBytes: 1 << 20,
+       }
+       log.Fatal(s.ListenAndServe())
+*/
+package http

diff --git a/src/pkg/http/request.go b/src/pkg/http/request.go
index 02317e0c41944317e9e0c8afbbe9547dab8d2410..78e07ecbc97eae38b25d8d5629377385ef775d75 100644 (file)
--- a/src/pkg/http/request.go
+++ b/src/pkg/http/request.go
@@ -4,8 +4,6 @@
 
 // HTTP Request reading and parsing.
 
-// Package http implements parsing of HTTP requests, replies, and URLs and
-// provides an extensible HTTP server and a basic HTTP client.
 package http
 
 import (