net/http: document that [ListenAnd]Serve always returns a non-nil error

Fixes #12229

Change-Id: I243e39f67748e6754fb7726b21b3afc1ff436771
Reviewed-on: https://go-review.googlesource.com/13780
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/net/http/server.go b/src/net/http/server.go
index a3e43555bb37b4f120deeec2e5bd16277976b29d..2c01feeb80778beb7a4f14b14f32359931ad99d5 100644 (file)
--- a/src/net/http/server.go
+++ b/src/net/http/server.go
@@ -1863,8 +1863,9 @@ func (sh serverHandler) ServeHTTP(rw ResponseWriter, req *Request) {
 }
 
 // ListenAndServe listens on the TCP network address srv.Addr and then
-// calls Serve to handle requests on incoming connections.  If
-// srv.Addr is blank, ":http" is used.
+// calls Serve to handle requests on incoming connections.
+// If srv.Addr is blank, ":http" is used.
+// ListenAndServe always returns a non-nil error.
 func (srv *Server) ListenAndServe() error {
        addr := srv.Addr
        if addr == "" {
@@ -1878,8 +1879,9 @@ func (srv *Server) ListenAndServe() error {
 }
 
 // Serve accepts incoming connections on the Listener l, creating a
-// new service goroutine for each.  The service goroutines read requests and
+// new service goroutine for each. The service goroutines read requests and
 // then call srv.Handler to reply to them.
+// Serve always returns a non-nil error.
 func (srv *Server) Serve(l net.Listener) error {
        defer l.Close()
        var tempDelay time.Duration // how long to sleep on accept failure
@@ -1957,11 +1959,10 @@ func (s *Server) logf(format string, args ...interface{}) {
 //
 //     func main() {
 //             http.HandleFunc("/hello", HelloServer)
-//             err := http.ListenAndServe(":12345", nil)
-//             if err != nil {
-//                     log.Fatal("ListenAndServe: ", err)
-//             }
+//             log.Fatal(http.ListenAndServe(":12345", nil))
 //     }
+//
+// ListenAndServe always returns a non-nil error.
 func ListenAndServe(addr string, handler Handler) error {
        server := &Server{Addr: addr, Handler: handler}
        return server.ListenAndServe()
@@ -1989,12 +1990,12 @@ func ListenAndServe(addr string, handler Handler) error {
 //             http.HandleFunc("/", handler)
 //             log.Printf("About to listen on 10443. Go to https://127.0.0.1:10443/")
 //             err := http.ListenAndServeTLS(":10443", "cert.pem", "key.pem", nil)
-//             if err != nil {
-//                     log.Fatal(err)
-//             }
+//             log.Fatal(err)
 //     }
 //
 // One can use generate_cert.go in crypto/tls to generate cert.pem and key.pem.
+//
+// ListenAndServeTLS always returns a non-nil error.
 func ListenAndServeTLS(addr string, certFile string, keyFile string, handler Handler) error {
        server := &Server{Addr: addr, Handler: handler}
        return server.ListenAndServeTLS(certFile, keyFile)
@@ -2010,6 +2011,8 @@ func ListenAndServeTLS(addr string, certFile string, keyFile string, handler Han
 // certificate, any intermediates, and the CA's certificate.
 //
 // If srv.Addr is blank, ":https" is used.
+//
+// ListenAndServeTLS always returns a non-nil error.
 func (srv *Server) ListenAndServeTLS(certFile, keyFile string) error {
        addr := srv.Addr
        if addr == "" {

diff --git a/src/net/http/triv.go b/src/net/http/triv.go
index 232d6508906328a53855a995cd63db02bcc3f477..cfbc5778c1cc499097a3362e4dca3b350dd664cb 100644 (file)
--- a/src/net/http/triv.go
+++ b/src/net/http/triv.go
@@ -134,8 +134,5 @@ func main() {
        http.HandleFunc("/args", ArgServer)
        http.HandleFunc("/go/hello", HelloServer)
        http.HandleFunc("/date", DateServer)
-       err := http.ListenAndServe(":12345", nil)
-       if err != nil {
-               log.Panicln("ListenAndServe:", err)
-       }
+       log.Fatal(http.ListenAndServe(":12345", nil))
 }