Improved godocs

Author: obeattie

buffer.go

@@ -19,8 +19,18 @@ type streamer struct {
 	pipeW *io.PipeWriter
 }
 
-// Streamer returns a reader/writer/closer that can be used to stream service responses. It does not necessarily
-// perform internal buffering, so users should take care not to depend on such behaviour.
+// Streamer returns a reader/writer/closer that can be used to stream responses. A simple use of this is:
+//  func streamingService(req typhon.Request) typhon.Response {
+//      body := typhon.Streamer()
+//      go func() {
+//          defer body.Close()
+//          // do something to asynchronously produce output into body
+//      }()
+//      return req.Response(body)
+//  }
+//
+// Note that a Streamer may not perform any internal buffering, so callers should take care not to depend on writes
+// being non-blocking. If buffering is needed, Streamer can be wrapped in a bufio.Writer.
 func Streamer() io.ReadWriteCloser {
 	pipeR, pipeW := io.Pipe()
 	return &streamer{

client.go

@@ -71,7 +71,8 @@ func BareClient(req Request) Response {
 	return HttpService(RoundTripper)(req)
 }
 
-// SendVia sends the given request via the given service, returning a future representing the operation
+// SendVia round-trips the request via the passed Service. It does not block, instead returning a ResponseFuture
+// representing the asynchronous operation to produce the response.
 func SendVia(req Request, svc Service) *ResponseFuture {
 	done := make(chan struct{}, 0)
 	f := &ResponseFuture{
@@ -83,7 +84,10 @@ func SendVia(req Request, svc Service) *ResponseFuture {
 	return f
 }
 
-// Send is equivalent to SendVia(req, Client)
+// Send round-trips the request via the default Client. It does not block, instead returning a ResponseFuture
+// representing the asynchronous operation to produce the response. It is equivalent to:
+//
+//  SendVia(req, Client)
 func Send(req Request) *ResponseFuture {
 	return SendVia(req, Client)
 }

doc.go

@@ -0,0 +1,5 @@
+/*
+Package typhon wraps net/http to provide a simple yet powerful programming model for RPC servers and clients. At Monzo,
+it is used to implement the majority of our Go microservices.
+*/
+package typhon

terrors.go renamed to errors.go

@@ -33,7 +33,9 @@ func init() {
 	}
 }
 
-// ErrorStatusCode returns an HTTP status code for the error
+// ErrorStatusCode returns a HTTP status code for the given error.
+//
+// If the error is not a terror, this will always be 500 (Internal Server Error).
 func ErrorStatusCode(err error) int {
 	code := terrors.Wrap(err, nil).(*terrors.Error).Code
 	if c, ok := mapTerr2Status[strings.SplitN(code, ".", 2)[0]]; ok {
@@ -50,7 +52,8 @@ func status2TerrCode(code int) string {
 	return terrors.ErrInternalService
 }
 
-// ErrorFilter serialises and de-serialises response errors
+// ErrorFilter serialises and deserialises response errors. Without this filter, errors may not be passed across
+// the network properly so it is recommended to use this in most/all cases.
 func ErrorFilter(req Request, svc Service) Response {
 	// If the request contains an error, short-circuit and return that directly
 	var rsp Response

filter.go

@@ -1,5 +1,8 @@
 package typhon
 
-// Filter functions compose with Services to modify their observed behaviour. They might change a service's input or
-// output, or elect not to call the underlying service at all.
+// Filter functions compose with Services to modify their behaviour. They might change a service's input or output, or
+// elect not to call the underlying service at all.
+//
+// These are typically useful to encapsulate common logic that is shared among multiple Services. Authentication,
+// authorisation, rate limiting, and tracing are good examples.
 type Filter func(Request, Service) Response

http.go

@@ -77,7 +77,8 @@ func copyErrSeverity(err error) slog.Severity {
 	}
 }
 
-// HttpHandler transforms the given Service into a http.Handler, suitable for use directly with net/http
+// HttpHandler transforms the given Service into a standard library HTTP handler. It is one of the main "bridges"
+// between Typhon and net/http.
 func HttpHandler(svc Service) http.Handler {
 	return http.HandlerFunc(func(rw http.ResponseWriter, httpReq *http.Request) {
 		if httpReq.Body != nil {

request.go

@@ -72,6 +72,7 @@ func (r Request) Decode(v interface{}) error {
 	return terrors.WrapWithCode(err, nil, terrors.ErrBadRequest)
 }
 
+// Write writes the passed bytes to the request's body.
 func (r *Request) Write(b []byte) (int, error) {
 	switch rc := r.Body.(type) {
 	// In the "normal" case, the response body will be a buffer, to which we can write
@@ -94,8 +95,10 @@ func (r *Request) Write(b []byte) (int, error) {
 	}
 }
 
-// BodyBytes fully reads the request body and returns the bytes read. If consume is false, the body is copied into a
-// new buffer such that it may be read again.
+// BodyBytes fully reads the request body and returns the bytes read.
+//
+// If consume is true, this is equivalent to ioutil.ReadAll; if false, the caller will observe the body to be in
+// the same state that it was before (ie. any remaining unread body can be read again).
 func (r *Request) BodyBytes(consume bool) ([]byte, error) {
 	if consume {
 		defer r.Body.Close()
@@ -115,10 +118,16 @@ func (r *Request) BodyBytes(consume bool) ([]byte, error) {
 	}
 }
 
+// Send round-trips the request via the default Client. It does not block, instead returning a ResponseFuture
+// representing the asynchronous operation to produce the response. It is equivalent to:
+//
+//  r.SendVia(Client)
 func (r Request) Send() *ResponseFuture {
 	return Send(r)
 }
 
+// SendVia round-trips the request via the passed Service. It does not block, instead returning a ResponseFuture
+// representing the asynchronous operation to produce the response.
 func (r Request) SendVia(svc Service) *ResponseFuture {
 	return SendVia(r, svc)
 }

response.go

@@ -71,6 +71,7 @@ func (r *Response) Decode(v interface{}) error {
 	return err
 }
 
+// Write writes the passed bytes to the response's body.
 func (r *Response) Write(b []byte) (int, error) {
 	if r.Response == nil {
 		r.Response = newHTTPResponse(Request{})
@@ -118,7 +119,10 @@ func (r *Response) BodyBytes(consume bool) ([]byte, error) {
 	}
 }
 
-// Writer returns a ResponseWriter proxy.
+// Writer returns a ResponseWriter which can be used to populate the response.
+//
+// This is useful when you want to use another HTTP library that is used to wrapping net/http directly. For example,
+// it allows a Typhon Service to use a http.Handler internally.
 func (r *Response) Writer() ResponseWriter {
 	if r.Request != nil && r.Request.hijacker != nil {
 		return hijackerRw{

router.go

@@ -127,47 +127,56 @@ func (r Router) Params(req Request) map[string]string {
 
 // Sugar
 
-// GET is shorthand for Register("GET", pattern, svc).
+// GET is shorthand for:
+//  r.Register("GET", pattern, svc)
 //
 // Pattern syntax is as described in echo's documentation: https://echo.labstack.com/guide/routing
 func (r *Router) GET(pattern string, svc Service) { r.Register("GET", pattern, svc) }
 
-// CONNECT is shorthand for Register("CONNECT", pattern, svc).
+// CONNECT is shorthand for:
+//  r.Register("CONNECT", pattern, svc)
 //
 // Pattern syntax is as described in echo's documentation: https://echo.labstack.com/guide/routing
 func (r *Router) CONNECT(pattern string, svc Service) { r.Register("CONNECT", pattern, svc) }
 
-// DELETE is shorthand for Register("DELETE", pattern, svc).
+// DELETE is shorthand for:
+//  r.Register("DELETE", pattern, svc)
 //
 // Pattern syntax is as described in echo's documentation: https://echo.labstack.com/guide/routing
 func (r *Router) DELETE(pattern string, svc Service) { r.Register("DELETE", pattern, svc) }
 
-// HEAD is shorthand for Register("HEAD", pattern, svc).
+// HEAD is shorthand for:
+//  r.Register("HEAD", pattern, svc)
 //
 // Pattern syntax is as described in echo's documentation: https://echo.labstack.com/guide/routing
 func (r *Router) HEAD(pattern string, svc Service) { r.Register("HEAD", pattern, svc) }
 
-// OPTIONS is shorthand for Register("OPTIONS", pattern, svc).
+// OPTIONS is shorthand for:
+//  r.Register("OPTIONS", pattern, svc)
 //
 // Pattern syntax is as described in echo's documentation: https://echo.labstack.com/guide/routing
 func (r *Router) OPTIONS(pattern string, svc Service) { r.Register("OPTIONS", pattern, svc) }
 
-// PATCH is shorthand for Register("PATCH", pattern, svc).
+// PATCH is shorthand for:
+//  r.Register("PATCH", pattern, svc)
 //
 // Pattern syntax is as described in echo's documentation: https://echo.labstack.com/guide/routing
 func (r *Router) PATCH(pattern string, svc Service) { r.Register("PATCH", pattern, svc) }
 
-// POST is shorthand for Register("POST", pattern, svc).
+// POST is shorthand for:
+//  r.Register("POST", pattern, svc)
 //
 // Pattern syntax is as described in echo's documentation: https://echo.labstack.com/guide/routing
 func (r *Router) POST(pattern string, svc Service) { r.Register("POST", pattern, svc) }
 
-// PUT is shorthand for Register("PUT", pattern, svc).
+// PUT is shorthand for:
+//  r.Register("PUT", pattern, svc)
 //
 // Pattern syntax is as described in echo's documentation: https://echo.labstack.com/guide/routing
 func (r *Router) PUT(pattern string, svc Service) { r.Register("PUT", pattern, svc) }
 
-// TRACE is shorthand for Register("TRACE", pattern, svc).
+// TRACE is shorthand for:
+//  r.Register("TRACE", pattern, svc)
 //
 // Pattern syntax is as described in echo's documentation: https://echo.labstack.com/guide/routing
 func (r *Router) TRACE(pattern string, svc Service) { r.Register("TRACE", pattern, svc) }