Fix function comments based on best practices from Effective Go

rest/access_log_apache.go

@@ -171,31 +171,31 @@ type accessLogUtil struct {
 	R *Request
 }
 
-// As stored by the auth middlewares.
+// RemoteUser: As stored by the auth middlewares.
 func (u *accessLogUtil) RemoteUser() string {
 	if u.R.Env["REMOTE_USER"] != nil {
 		return u.R.Env["REMOTE_USER"].(string)
 	}
 	return ""
 }
 
-// If qs exists then return it with a leadin "?", apache log style.
+// ApacheQueryString: If qs exists then return it with a leadin "?", apache log style.
 func (u *accessLogUtil) ApacheQueryString() string {
 	if u.R.URL.RawQuery != "" {
 		return "?" + u.R.URL.RawQuery
 	}
 	return ""
 }
 
-// When the request entered the timer middleware.
+// StartTime: When the request entered the timer middleware.
 func (u *accessLogUtil) StartTime() *time.Time {
 	if u.R.Env["START_TIME"] != nil {
 		return u.R.Env["START_TIME"].(*time.Time)
 	}
 	return nil
 }
 
-// If remoteAddr is set then return is without the port number, apache log style.
+// ApacheRemoteAddr: If remoteAddr is set then return is without the port number, apache log style.
 func (u *accessLogUtil) ApacheRemoteAddr() string {
 	remoteAddr := u.R.RemoteAddr
 	if remoteAddr != "" {
@@ -206,28 +206,28 @@ func (u *accessLogUtil) ApacheRemoteAddr() string {
 	return ""
 }
 
-// As recorded by the recorder middleware.
+// StatusCode: As recorded by the recorder middleware.
 func (u *accessLogUtil) StatusCode() int {
 	if u.R.Env["STATUS_CODE"] != nil {
 		return u.R.Env["STATUS_CODE"].(int)
 	}
 	return 0
 }
 
-// As mesured by the timer middleware.
+// ResponseTime: As mesured by the timer middleware.
 func (u *accessLogUtil) ResponseTime() *time.Duration {
 	if u.R.Env["ELAPSED_TIME"] != nil {
 		return u.R.Env["ELAPSED_TIME"].(*time.Duration)
 	}
 	return nil
 }
 
-// Process id.
+// Pid: Process id.
 func (u *accessLogUtil) Pid() int {
 	return os.Getpid()
 }
 
-// As recorded by the recorder middleware.
+// BytesWritten: As recorded by the recorder middleware.
 func (u *accessLogUtil) BytesWritten() int64 {
 	if u.R.Env["BYTES_WRITTEN"] != nil {
 		return u.R.Env["BYTES_WRITTEN"].(int64)

rest/gzip.go

@@ -47,7 +47,7 @@ type gzipResponseWriter struct {
 	gzipWriter  *gzip.Writer
 }
 
-// Set the right headers for gzip encoded responses.
+// WriteHeader: Set the right headers for gzip encoded responses.
 func (w *gzipResponseWriter) WriteHeader(code int) {
 
 	// Always set the Vary header, even if this particular request
@@ -62,7 +62,7 @@ func (w *gzipResponseWriter) WriteHeader(code int) {
 	w.wroteHeader = true
 }
 
-// Make sure the local Write is called.
+// WriteJson: Make sure the local Write is called.
 func (w *gzipResponseWriter) WriteJson(v interface{}) error {
 	b, err := w.EncodeJson(v)
 	if err != nil {
@@ -75,7 +75,7 @@ func (w *gzipResponseWriter) WriteJson(v interface{}) error {
 	return nil
 }
 
-// Make sure the local WriteHeader is called, and call the parent Flush.
+// Flush: Make sure the local WriteHeader is called, and call the parent Flush.
 // Provided in order to implement the http.Flusher interface.
 func (w *gzipResponseWriter) Flush() {
 	if !w.wroteHeader {
@@ -85,20 +85,20 @@ func (w *gzipResponseWriter) Flush() {
 	flusher.Flush()
 }
 
-// Call the parent CloseNotify.
+// CloseNotify: Call the parent CloseNotify.
 // Provided in order to implement the http.CloseNotifier interface.
 func (w *gzipResponseWriter) CloseNotify() <-chan bool {
 	notifier := w.ResponseWriter.(http.CloseNotifier)
 	return notifier.CloseNotify()
 }
 
-// Provided in order to implement the http.Hijacker interface.
+// Hijack: Provided in order to implement the http.Hijacker interface.
 func (w *gzipResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
 	hijacker := w.ResponseWriter.(http.Hijacker)
 	return hijacker.Hijack()
 }
 
-// Make sure the local WriteHeader is called, and encode the payload if necessary.
+// Write: Make sure the local WriteHeader is called, and encode the payload if necessary.
 // Provided in order to implement the http.ResponseWriter interface.
 func (w *gzipResponseWriter) Write(b []byte) (int, error) {
 

rest/json_indent.go

@@ -50,7 +50,7 @@ type jsonIndentResponseWriter struct {
 	indent      string
 }
 
-// Replace the parent EncodeJson to provide indentation.
+// EncodeJson replaces the parent EncodeJson to provide indentation.
 func (w *jsonIndentResponseWriter) EncodeJson(v interface{}) ([]byte, error) {
 	b, err := json.MarshalIndent(v, w.prefix, w.indent)
 	if err != nil {
@@ -59,7 +59,7 @@ func (w *jsonIndentResponseWriter) EncodeJson(v interface{}) ([]byte, error) {
 	return b, nil
 }
 
-// Make sure the local EncodeJson and local Write are called.
+// WriteJson: Make sure the local EncodeJson and local Write are called.
 // Does not call the parent WriteJson.
 func (w *jsonIndentResponseWriter) WriteJson(v interface{}) error {
 	b, err := w.EncodeJson(v)
@@ -73,13 +73,13 @@ func (w *jsonIndentResponseWriter) WriteJson(v interface{}) error {
 	return nil
 }
 
-// Call the parent WriteHeader.
+// WriteHeader: Call the parent WriteHeader.
 func (w *jsonIndentResponseWriter) WriteHeader(code int) {
 	w.ResponseWriter.WriteHeader(code)
 	w.wroteHeader = true
 }
 
-// Make sure the local WriteHeader is called, and call the parent Flush.
+// Flush: Make sure the local WriteHeader is called, and call the parent Flush.
 // Provided in order to implement the http.Flusher interface.
 func (w *jsonIndentResponseWriter) Flush() {
 	if !w.wroteHeader {
@@ -89,20 +89,20 @@ func (w *jsonIndentResponseWriter) Flush() {
 	flusher.Flush()
 }
 
-// Call the parent CloseNotify.
+// CloseNotify: Call the parent CloseNotify.
 // Provided in order to implement the http.CloseNotifier interface.
 func (w *jsonIndentResponseWriter) CloseNotify() <-chan bool {
 	notifier := w.ResponseWriter.(http.CloseNotifier)
 	return notifier.CloseNotify()
 }
 
-// Provided in order to implement the http.Hijacker interface.
+// Hijack: Provided in order to implement the http.Hijacker interface.
 func (w *jsonIndentResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
 	hijacker := w.ResponseWriter.(http.Hijacker)
 	return hijacker.Hijack()
 }
 
-// Make sure the local WriteHeader is called, and call the parent Write.
+// Write: Make sure the local WriteHeader is called, and call the parent Write.
 // Provided in order to implement the http.ResponseWriter interface.
 func (w *jsonIndentResponseWriter) Write(b []byte) (int, error) {
 	if !w.wroteHeader {

rest/jsonp.go

@@ -55,7 +55,7 @@ type jsonpResponseWriter struct {
 	callbackName string
 }
 
-// Overwrite the Content-Type to be text/javascript
+// WriteHeader: Overwrite the Content-Type to be text/javascript
 func (w *jsonpResponseWriter) WriteHeader(code int) {
 
 	w.Header().Set("Content-Type", "text/javascript")
@@ -64,7 +64,7 @@ func (w *jsonpResponseWriter) WriteHeader(code int) {
 	w.wroteHeader = true
 }
 
-// Make sure the local Write is called.
+// WriteJson: Make sure the local Write is called.
 func (w *jsonpResponseWriter) WriteJson(v interface{}) error {
 	b, err := w.EncodeJson(v)
 	if err != nil {
@@ -79,7 +79,7 @@ func (w *jsonpResponseWriter) WriteJson(v interface{}) error {
 	return nil
 }
 
-// Make sure the local WriteHeader is called, and call the parent Flush.
+// Flush: Make sure the local WriteHeader is called, and call the parent Flush.
 // Provided in order to implement the http.Flusher interface.
 func (w *jsonpResponseWriter) Flush() {
 	if !w.wroteHeader {
@@ -89,20 +89,20 @@ func (w *jsonpResponseWriter) Flush() {
 	flusher.Flush()
 }
 
-// Call the parent CloseNotify.
+// CloseNotify: Call the parent CloseNotify.
 // Provided in order to implement the http.CloseNotifier interface.
 func (w *jsonpResponseWriter) CloseNotify() <-chan bool {
 	notifier := w.ResponseWriter.(http.CloseNotifier)
 	return notifier.CloseNotify()
 }
 
-// Provided in order to implement the http.Hijacker interface.
+// Hijack: Provided in order to implement the http.Hijacker interface.
 func (w *jsonpResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
 	hijacker := w.ResponseWriter.(http.Hijacker)
 	return hijacker.Hijack()
 }
 
-// Make sure the local WriteHeader is called.
+// Write: Make sure the local WriteHeader is called.
 // Provided in order to implement the http.ResponseWriter interface.
 func (w *jsonpResponseWriter) Write(b []byte) (int, error) {
 

rest/recorder.go

@@ -41,7 +41,7 @@ type recorderResponseWriter struct {
 	bytesWritten int64
 }
 
-// Record the status code.
+// WriteHeader: Record the status code.
 func (w *recorderResponseWriter) WriteHeader(code int) {
 	w.ResponseWriter.WriteHeader(code)
 	if w.wroteHeader {
@@ -51,7 +51,7 @@ func (w *recorderResponseWriter) WriteHeader(code int) {
 	w.wroteHeader = true
 }
 
-// Make sure the local Write is called.
+// WriteJson: Make sure the local Write is called.
 func (w *recorderResponseWriter) WriteJson(v interface{}) error {
 	b, err := w.EncodeJson(v)
 	if err != nil {
@@ -64,7 +64,7 @@ func (w *recorderResponseWriter) WriteJson(v interface{}) error {
 	return nil
 }
 
-// Make sure the local WriteHeader is called, and call the parent Flush.
+// Flush: Make sure the local WriteHeader is called, and call the parent Flush.
 // Provided in order to implement the http.Flusher interface.
 func (w *recorderResponseWriter) Flush() {
 	if !w.wroteHeader {
@@ -74,20 +74,20 @@ func (w *recorderResponseWriter) Flush() {
 	flusher.Flush()
 }
 
-// Call the parent CloseNotify.
+// CloseNotify: Call the parent CloseNotify.
 // Provided in order to implement the http.CloseNotifier interface.
 func (w *recorderResponseWriter) CloseNotify() <-chan bool {
 	notifier := w.ResponseWriter.(http.CloseNotifier)
 	return notifier.CloseNotify()
 }
 
-// Provided in order to implement the http.Hijacker interface.
+// Hijack: Provided in order to implement the http.Hijacker interface.
 func (w *recorderResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
 	hijacker := w.ResponseWriter.(http.Hijacker)
 	return hijacker.Hijack()
 }
 
-// Make sure the local WriteHeader is called, and call the parent Write.
+// Write: Make sure the local WriteHeader is called, and call the parent Write.
 // Provided in order to implement the http.ResponseWriter interface.
 func (w *recorderResponseWriter) Write(b []byte) (int, error) {
 	if !w.wroteHeader {

rest/recorder_test.go

@@ -52,7 +52,7 @@ func TestRecorderMiddleware(t *testing.T) {
 	recorded.ContentTypeIsJson()
 }
 
-// See how many bytes are written when gzipping
+// TestRecorderAndGzipMiddleware: See how many bytes are written when gzipping
 func TestRecorderAndGzipMiddleware(t *testing.T) {
 
 	api := NewApi()
@@ -93,7 +93,7 @@ func TestRecorderAndGzipMiddleware(t *testing.T) {
 	recorded.ContentTypeIsJson()
 }
 
-//Underlying net/http only allows you to set the status code once
+// TestRecorderMiddlewareReportsSameStatusCodeAsResponse: Underlying net/http only allows you to set the status code once
 func TestRecorderMiddlewareReportsSameStatusCodeAsResponse(t *testing.T) {
 	api := NewApi()
 	const firstCode = 400

rest/response.go

@@ -84,7 +84,7 @@ func (w *responseWriter) EncodeJson(v interface{}) ([]byte, error) {
 	return b, nil
 }
 
-// Encode the object in JSON and call Write.
+// WriteJson: Encode the object in JSON and call Write.
 func (w *responseWriter) WriteJson(v interface{}) error {
 	b, err := w.EncodeJson(v)
 	if err != nil {
@@ -97,15 +97,15 @@ func (w *responseWriter) WriteJson(v interface{}) error {
 	return nil
 }
 
-// Provided in order to implement the http.ResponseWriter interface.
+// Write: Provided in order to implement the http.ResponseWriter interface.
 func (w *responseWriter) Write(b []byte) (int, error) {
 	if !w.wroteHeader {
 		w.WriteHeader(http.StatusOK)
 	}
 	return w.ResponseWriter.Write(b)
 }
 
-// Provided in order to implement the http.Flusher interface.
+// Flush: Provided in order to implement the http.Flusher interface.
 func (w *responseWriter) Flush() {
 	if !w.wroteHeader {
 		w.WriteHeader(http.StatusOK)
@@ -114,13 +114,13 @@ func (w *responseWriter) Flush() {
 	flusher.Flush()
 }
 
-// Provided in order to implement the http.CloseNotifier interface.
+// CloseNotify: Provided in order to implement the http.CloseNotifier interface.
 func (w *responseWriter) CloseNotify() <-chan bool {
 	notifier := w.ResponseWriter.(http.CloseNotifier)
 	return notifier.CloseNotify()
 }
 
-// Provided in order to implement the http.Hijacker interface.
+// Hijack: Provided in order to implement the http.Hijacker interface.
 func (w *responseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
 	hijacker := w.ResponseWriter.(http.Hijacker)
 	return hijacker.Hijack()

rest/router.go

@@ -29,7 +29,7 @@ func MakeRouter(routes ...*Route) (App, error) {
 	return r, nil
 }
 
-// Handle the REST routing and run the user code.
+// AppFunc handles the REST routing and run the user code.
 func (rt *router) AppFunc() HandlerFunc {
 	return func(writer ResponseWriter, request *Request) {
 

rest/trie/impl.go

@@ -338,19 +338,19 @@ type Trie struct {
 	root *node
 }
 
-// Instanciate a Trie with an empty node as the root.
+// New: Instanciate a Trie with an empty node as the root.
 func New() *Trie {
 	return &Trie{
 		root: &node{},
 	}
 }
 
-// Insert the route in the Trie following or creating the nodes corresponding to the path.
+// AddRoute: Insert the route in the Trie following or creating the nodes corresponding to the path.
 func (t *Trie) AddRoute(httpMethod, pathExp string, route interface{}) error {
 	return t.root.addRoute(httpMethod, pathExp, route, []string{})
 }
 
-// Reduce the size of the tree, must be done after the last AddRoute.
+// Compress: Reduce the size of the tree, must be done after the last AddRoute.
 func (t *Trie) Compress() {
 	t.root.compress()
 }
@@ -362,7 +362,7 @@ func (t *Trie) printDebug() {
 	fmt.Print("</trie>\n")
 }
 
-// Given a path and an http method, return all the matching routes.
+// FindRoutes: Given a path and an http method, return all the matching routes.
 func (t *Trie) FindRoutes(httpMethod, path string) []*Match {
 	context := newFindContext()
 	matches := []*Match{}
@@ -382,7 +382,7 @@ func (t *Trie) FindRoutes(httpMethod, path string) []*Match {
 	return matches
 }
 
-// Same as FindRoutes, but return in addition a boolean indicating if the path was matched.
+// FindRoutesAndPathMatched: Same as FindRoutes, but return in addition a boolean indicating if the path was matched.
 // Useful to return 405
 func (t *Trie) FindRoutesAndPathMatched(httpMethod, path string) ([]*Match, bool) {
 	context := newFindContext()
@@ -405,7 +405,7 @@ func (t *Trie) FindRoutesAndPathMatched(httpMethod, path string) ([]*Match, bool
 	return matches, pathMatched
 }
 
-// Given a path, and whatever the http method, return all the matching routes.
+// FindRoutesForPath: Given a path, and whatever the http method, return all the matching routes.
 func (t *Trie) FindRoutesForPath(path string) []*Match {
 	context := newFindContext()
 	matches := []*Match{}