Included documented names in documentation.

bind/bind.go

@@ -95,9 +95,9 @@ func Socket(bind string) net.Listener {
 	return l
 }
 
-// Parse and bind to the default socket as given to us by the flag module. If
-// there was an error parsing or binding to that socket, Default will exit by
-// calling `log.Fatal`.
+// Default parses and binds to the default socket as given to us by the flag
+// module. If there was an error parsing or binding to that socket, Default will
+// exit by calling `log.Fatal`.
 func Default() net.Listener {
 	return Socket(bind)
 }
@@ -106,9 +106,10 @@ func Default() net.Listener {
 // as well be safe against it...
 var ready sync.Once
 
-// Notify the environment (for now, just Einhorn) that the process is ready to
-// receive traffic. Should be called at the last possible moment to maximize the
-// chances that a faulty process exits before signaling that it's ready.
+// Ready notifies the environment (for now, just Einhorn) that the process is
+// ready to receive traffic. Should be called at the last possible moment to
+// maximize the chances that a faulty process exits before signaling that it's
+// ready.
 func Ready() {
 	ready.Do(func() {
 		einhornAck()

default.go

@@ -17,8 +17,8 @@ func init() {
 	DefaultMux.Use(middleware.AutomaticOptions)
 }
 
-// Append the given middleware to the default Mux's middleware stack. See the
-// documentation for web.Mux.Use for more information.
+// Use appends the given middleware to the default Mux's middleware stack. See
+// the documentation for web.Mux.Use for more information.
 func Use(middleware interface{}) {
 	DefaultMux.Use(middleware)
 }
@@ -29,74 +29,74 @@ func Insert(middleware, before interface{}) error {
 	return DefaultMux.Insert(middleware, before)
 }
 
-// Remove the given middleware from the default Mux's middleware stack. See the
-// documentation for web.Mux.Abandon for more information.
+// Abandon removes the given middleware from the default Mux's middleware stack.
+// See the documentation for web.Mux.Abandon for more information.
 func Abandon(middleware interface{}) error {
 	return DefaultMux.Abandon(middleware)
 }
 
-// Add a route to the default Mux. See the documentation for web.Mux for more
-// information about what types this function accepts.
+// Handle adds a route to the default Mux. See the documentation for web.Mux for
+// more information about what types this function accepts.
 func Handle(pattern interface{}, handler interface{}) {
 	DefaultMux.Handle(pattern, handler)
 }
 
-// Add a CONNECT route to the default Mux. See the documentation for web.Mux for
-// more information about what types this function accepts.
+// Connect adds a CONNECT route to the default Mux. See the documentation for
+// web.Mux for more information about what types this function accepts.
 func Connect(pattern interface{}, handler interface{}) {
 	DefaultMux.Connect(pattern, handler)
 }
 
-// Add a DELETE route to the default Mux. See the documentation for web.Mux for
-// more information about what types this function accepts.
+// Delete adds a DELETE route to the default Mux. See the documentation for
+// web.Mux for more information about what types this function accepts.
 func Delete(pattern interface{}, handler interface{}) {
 	DefaultMux.Delete(pattern, handler)
 }
 
-// Add a GET route to the default Mux. See the documentation for web.Mux for
+// Get adds a GET route to the default Mux. See the documentation for web.Mux for
 // more information about what types this function accepts.
 func Get(pattern interface{}, handler interface{}) {
 	DefaultMux.Get(pattern, handler)
 }
 
-// Add a HEAD route to the default Mux. See the documentation for web.Mux for
-// more information about what types this function accepts.
+// Head adds a HEAD route to the default Mux. See the documentation for web.Mux
+// for more information about what types this function accepts.
 func Head(pattern interface{}, handler interface{}) {
 	DefaultMux.Head(pattern, handler)
 }
 
-// Add a OPTIONS route to the default Mux. See the documentation for web.Mux for
-// more information about what types this function accepts.
+// Options adds a OPTIONS route to the default Mux. See the documentation for
+// web.Mux for more information about what types this function accepts.
 func Options(pattern interface{}, handler interface{}) {
 	DefaultMux.Options(pattern, handler)
 }
 
-// Add a PATCH route to the default Mux. See the documentation for web.Mux for
-// more information about what types this function accepts.
+// Patch adds a PATCH route to the default Mux. See the documentation for web.Mux
+// for more information about what types this function accepts.
 func Patch(pattern interface{}, handler interface{}) {
 	DefaultMux.Patch(pattern, handler)
 }
 
-// Add a POST route to the default Mux. See the documentation for web.Mux for
-// more information about what types this function accepts.
+// Post adds a POST route to the default Mux. See the documentation for web.Mux
+// for more information about what types this function accepts.
 func Post(pattern interface{}, handler interface{}) {
 	DefaultMux.Post(pattern, handler)
 }
 
-// Add a PUT route to the default Mux. See the documentation for web.Mux for
+// Put adds a PUT route to the default Mux. See the documentation for web.Mux for
 // more information about what types this function accepts.
 func Put(pattern interface{}, handler interface{}) {
 	DefaultMux.Put(pattern, handler)
 }
 
-// Add a TRACE route to the default Mux. See the documentation for web.Mux for
-// more information about what types this function accepts.
+// Trace adds a TRACE route to the default Mux. See the documentation for
+// web.Mux for more information about what types this function accepts.
 func Trace(pattern interface{}, handler interface{}) {
 	DefaultMux.Trace(pattern, handler)
 }
 
-// Set the NotFound handler for the default Mux. See the documentation for
-// web.Mux.NotFound for more information.
+// NotFound sets the NotFound handler for the default Mux. See the documentation
+// for web.Mux.NotFound for more information.
 func NotFound(handler interface{}) {
 	DefaultMux.NotFound(handler)
 }

example/main.go

@@ -71,8 +71,8 @@ func Root(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
-// Create a new greet (POST "/greets"). Creates a greet and redirects you to the
-// created greet.
+// NewGreet creates a new greet (POST "/greets"). Creates a greet and redirects
+// you to the created greet.
 //
 // To post a new greet, try this at a shell:
 // $ now=$(date +'%Y-%m-%mT%H:%M:%SZ')
@@ -96,7 +96,7 @@ func NewGreet(w http.ResponseWriter, r *http.Request) {
 	http.Redirect(w, r, url, http.StatusCreated)
 }
 
-// Get a given user and her greets (GET "/user/:name")
+// GetUser finds a given user and her greets (GET "/user/:name")
 func GetUser(c web.C, w http.ResponseWriter, r *http.Request) {
 	io.WriteString(w, "Gritter\n======\n\n")
 	handle := c.UrlParams["name"]
@@ -116,8 +116,8 @@ func GetUser(c web.C, w http.ResponseWriter, r *http.Request) {
 	}
 }
 
-// Get a particular greet by ID (GET "/greet/\d+"). Does no bounds checking, so
-// will probably panic.
+// GetGreet finds a particular greet by ID (GET "/greet/\d+"). Does no bounds
+// checking, so will probably panic.
 func GetGreet(c web.C, w http.ResponseWriter, r *http.Request) {
 	id, err := strconv.Atoi(c.UrlParams["id"])
 	if err != nil {
@@ -131,17 +131,18 @@ func GetGreet(c web.C, w http.ResponseWriter, r *http.Request) {
 	greet.Write(w)
 }
 
-// Admin root (GET "/admin/root"). Much secret. Very administrate. Wow.
+// AdminRoot is root (GET "/admin/root"). Much secret. Very administrate. Wow.
 func AdminRoot(w http.ResponseWriter, r *http.Request) {
 	io.WriteString(w, "Gritter\n======\n\nSuper secret admin page!\n")
 }
 
-// How are we doing? (GET "/admin/finances")
+// AdminFinances would answer the question 'How are we doing?'
+// (GET "/admin/finances")
 func AdminFinances(w http.ResponseWriter, r *http.Request) {
 	io.WriteString(w, "Gritter\n======\n\nWe're broke! :(\n")
 }
 
-// 404 handler.
+// NotFound is a 404 handler.
 func NotFound(w http.ResponseWriter, r *http.Request) {
 	http.Error(w, "Umm... have you tried turning it off and on again?", 404)
 }

example/middleware.go

@@ -8,7 +8,7 @@ import (
 	"github.com/zenazn/goji/web"
 )
 
-// Middleware to render responses as plain text.
+// PlainText sets the content-type of responses to text/plain.
 func PlainText(h http.Handler) http.Handler {
 	fn := func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "text/plain")
@@ -20,7 +20,7 @@ func PlainText(h http.Handler) http.Handler {
 // Nobody will ever guess this!
 const Password = "admin:admin"
 
-// HTTP Basic Auth middleware for super-secret admin page. Shhhh!
+// SuperSecure is HTTP Basic Auth middleware for super-secret admin page. Shhhh!
 func SuperSecure(c *web.C, h http.Handler) http.Handler {
 	fn := func(w http.ResponseWriter, r *http.Request) {
 		auth := r.Header.Get("Authorization")

example/models.go

@@ -6,7 +6,7 @@ import (
 	"time"
 )
 
-// A greet is a 140-character micro-blogpost that has no resemblance whatsoever
+// A Greet is a 140-character micro-blogpost that has no resemblance whatsoever
 // to the noise a bird makes.
 type Greet struct {
 	User    string    `param:"user"`
@@ -30,7 +30,8 @@ func (g Greet) Write(w io.Writer) {
 		g.Time.Format(time.UnixDate))
 }
 
-// A user
+// A User is a person. It may even be someone you know. Or a rabbit. Hard to say
+// from here.
 type User struct {
 	Name, Bio string
 }

goji.go

@@ -42,7 +42,7 @@ import (
 	"github.com/zenazn/goji/graceful"
 )
 
-// Start Goji using reasonable defaults.
+// Serve starts Goji using reasonable defaults.
 func Serve() {
 	if !flag.Parsed() {
 		flag.Parse()

graceful/middleware.go

@@ -8,9 +8,10 @@ import (
 )
 
 /*
-Graceful shutdown middleware. When a graceful shutdown is in progress, this
-middleware intercepts responses to add a "Connection: close" header to politely
-inform the client that we are about to go away.
+Middleware adds graceful shutdown capabilities to the given handler. When a
+graceful shutdown is in progress, this middleware intercepts responses to add a
+"Connection: close" header to politely inform the client that we are about to go
+away.
 
 This package creates a shim http.ResponseWriter that it passes to subsequent
 handlers. Unfortunately, there's a great many optional interfaces that this

graceful/net.go

@@ -15,9 +15,9 @@ type gracefulConn interface {
 	gracefulShutdown()
 }
 
-// Wrap an arbitrary net.Listener for use with graceful shutdowns. All
-// net.Conn's Accept()ed by this listener will be auto-wrapped as if WrapConn()
-// were called on them.
+// WrapListener wraps an arbitrary net.Listener for use with graceful shutdowns.
+// All net.Conn's Accept()ed by this listener will be auto-wrapped as if
+// WrapConn() were called on them.
 func WrapListener(l net.Listener) net.Listener {
 	return listener{l}
 }
@@ -32,9 +32,9 @@ func (l listener) Accept() (net.Conn, error) {
 }
 
 /*
-Wrap an arbitrary connection for use with graceful shutdowns. The graceful
-shutdown process will ensure that this connection is closed before terminating
-the process.
+WrapConn wraps an arbitrary connection for use with graceful shutdowns. The
+graceful shutdown process will ensure that this connection is closed before
+terminating the process.
 
 In order to use this function, you must call SetReadDeadline() before the call
 to Read() you might make to read a new request off the wire.  The connection is

graceful/signal.go

@@ -31,20 +31,21 @@ func init() {
 	go waitForSignal()
 }
 
-// Add the given signal to the set of signals that trigger a graceful shutdown.
-// Note that for convenience the default interrupt (SIGINT) handler is installed
-// at package load time, and unless you call ResetSignals() will be listened for
-// in addition to any signals you provide by calling this function.
+// AddSignal adds the given signal to the set of signals that trigger a graceful
+// shutdown. Note that for convenience the default interrupt (SIGINT) handler is
+// installed at package load time, and unless you call ResetSignals() will be
+// listened for in addition to any signals you provide by calling this function.
 func AddSignal(sig ...os.Signal) {
 	signal.Notify(sigchan, sig...)
 }
 
-// Reset the list of signals that trigger a graceful shutdown. Useful if, for
-// instance, you don't want to use the default interrupt (SIGINT) handler. Since
-// we necessarily install the SIGINT handler before you have a chance to call
-// ResetSignals(), there will be a brief window during which the set of signals
-// this package listens for will not be as you intend. Therefore, if you intend
-// on using this function, we encourage you to call it as soon as possible.
+// ResetSignals resets  the list of signals that trigger a graceful shutdown.
+// Useful if, for instance, you don't want to use the default interrupt (SIGINT)
+// handler. Since we necessarily install the SIGINT handler before you have a
+// chance to call ResetSignals(), there will be a brief window during which the
+// set of signals this package listens for will not be as you intend. Therefore,
+// if you intend on using this function, we encourage you to call it as soon as
+// possible.
 func ResetSignals() {
 	signal.Stop(sigchan)
 }
@@ -56,16 +57,16 @@ func (u userShutdown) String() string {
 }
 func (u userShutdown) Signal() {}
 
-// Manually trigger a shutdown from your application. Like Wait(), blocks until
-// all connections have gracefully shut down.
+// Shutdown manually trigger a shutdown from your application. Like Wait(),
+// blocks until all connections have gracefully shut down.
 func Shutdown() {
 	sigchan <- userShutdown{}
 	<-wait
 }
 
-// Register a function to be called before any of this package's normal shutdown
-// actions. All listeners will be called in the order they were added, from a
-// single goroutine.
+// PreHook registers a function to be called before any of this package's normal
+// shutdown actions. All listeners will be called in the order they were added,
+// from a single goroutine.
 func PreHook(f func()) {
 	hookLock.Lock()
 	defer hookLock.Unlock()
@@ -73,9 +74,9 @@ func PreHook(f func()) {
 	prehooks = append(prehooks, f)
 }
 
-// Register a function to be called after all of this package's normal shutdown
-// actions. All listeners will be called in the order they were added, from a
-// single goroutine, and are guaranteed to be called after all listening
+// PostHook registers a function to be called after all of this package's normal
+// shutdown actions. All listeners will be called in the order they were added,
+// from a single goroutine, and are guaranteed to be called after all listening
 // connections have been closed, but before Wait() returns.
 //
 // If you've Hijack()ed any connections that must be gracefully shut down in

web/middleware/options.go

@@ -9,8 +9,8 @@ import (
 	"github.com/zenazn/goji/web"
 )
 
-// Automatically return an appropriate "Allow" header when the request method is
-// OPTIONS and the request would have otherwise been 404'd.
+// AutomaticOptions automatically return an appropriate "Allow" header when the
+// request method is OPTIONS and the request would have otherwise been 404'd.
 func AutomaticOptions(c *web.C, h http.Handler) http.Handler {
 	fn := func(w http.ResponseWriter, r *http.Request) {
 		// This will probably slow down OPTIONS calls a bunch, but it

web/mux.go

@@ -5,7 +5,7 @@ import (
 )
 
 /*
-An HTTP multiplexer, much like net/http's ServeMux.
+Mux is an HTTP multiplexer, much like net/http's ServeMux.
 
 Routes may be added using any of the various HTTP-method-specific functions.
 When processing a request, when iterating in insertion order the first route
@@ -60,7 +60,7 @@ type Mux struct {
 var _ http.Handler = &Mux{}
 var _ Handler = &Mux{}
 
-// Create a new Mux without any routes or middleware.
+// New creates a new Mux without any routes or middleware.
 func New() *Mux {
 	mux := Mux{
 		mStack: mStack{
@@ -84,8 +84,8 @@ func (m *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	stack.ServeHTTP(w, r)
 }
 
-// Serve a context dependent request with the given Mux. Satisfies the
-// web.Handler interface.
+// ServeHTTPC creates a context dependent request with the given Mux. Satisfies
+// the web.Handler interface.
 func (m *Mux) ServeHTTPC(c C, w http.ResponseWriter, r *http.Request) {
 	stack := m.mStack.alloc()
 	defer m.mStack.release(stack)

web/router.go

@@ -61,7 +61,7 @@ type router struct {
 	notFound Handler
 }
 
-// A pattern determines whether or not a given request matches some criteria.
+// A Pattern determines whether or not a given request matches some criteria.
 // They are often used in routes, which are essentially (pattern, methodSet,
 // handler) tuples. If the method and pattern match, the given handler is used.
 //

web/web.go

@@ -78,8 +78,8 @@ import (
 )
 
 /*
-Per-request context object. Threaded through all compliant middleware layers and
-to the final request handler.
+C is a per-request context object which is threaded through all compliant middleware
+layers and to the final request handler.
 
 As an implementation detail, references to these structs are reused between
 requests to reduce allocation churn, but the maps they contain are created fresh
@@ -101,22 +101,23 @@ type C struct {
 	Env map[string]interface{}
 }
 
-// A superset of net/http's http.Handler, which also includes a mechanism for
-// serving requests with a context. If your handler does not support the use of
-// contexts, we encourage you to use http.Handler instead.
+// Handler is a superset of net/http's http.Handler, which also includes a
+// mechanism for serving requests with a context. If your handler does not
+// support the use of contexts, we encourage you to use http.Handler instead.
 type Handler interface {
 	http.Handler
 	ServeHTTPC(C, http.ResponseWriter, *http.Request)
 }
 
-// Like net/http's http.HandlerFunc, but supports a context object. Implements
-// both http.Handler and web.Handler free of charge.
+// HandlerFunc is like net/http's http.HandlerFunc, but supports a context
+// object. Implements both http.Handler and web.Handler free of charge.
 type HandlerFunc func(C, http.ResponseWriter, *http.Request)
 
 func (h HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	h(C{}, w, r)
 }
 
+// ServeHTTPC wraps ServeHTTP with a context parameter.
 func (h HandlerFunc) ServeHTTPC(c C, w http.ResponseWriter, r *http.Request) {
 	h(c, w, r)
 }