From 74498f1582f28a47eb71c02bdac61d7f5c998a78 Mon Sep 17 00:00:00 2001
From: Vincent Serpoul <vincent@serpoul.com>
Date: Fri, 8 Apr 2022 00:07:00 +0800
Subject: [PATCH] doc: add comments for public functions

---
 body.go           | 1 +
 error_response.go | 5 +++++
 response.go       | 1 +
 url_params.go     | 3 +++
 wrapper.go        | 2 ++
 5 files changed, 12 insertions(+)

diff --git a/body.go b/body.go
index c97c894..17c2fe5 100644
--- a/body.go
+++ b/body.go
@@ -10,6 +10,7 @@ const (
 	ErrCodeParsingBody = "error_parsing_body"
 )
 
+// BindBody will bind the body of the request to the given interface.
 func BindBody(r *http.Request, target interface{}) *ErrorResponse {
 	// nolint: gocritic
 	// LATER: add more encodings
diff --git a/error_response.go b/error_response.go
index 0393f5d..7f99b21 100644
--- a/error_response.go
+++ b/error_response.go
@@ -8,6 +8,7 @@ import (
 	"github.com/rs/zerolog"
 )
 
+// ErrorResponse is a wrapper for the error response body to have a clean way of displaying errors.
 type ErrorResponse struct {
 	Error          error  `json:"-"`
 	HTTPStatusCode int    `json:"-"`
@@ -15,6 +16,7 @@ type ErrorResponse struct {
 	ErrorMsg       string `json:"error_msg"`
 }
 
+// NewErrorResponse creates a new ErrorResponse.
 func NewErrorResponse(
 	e error,
 	hsc int,
@@ -39,6 +41,7 @@ func (her *ErrorResponse) render(log zerolog.Logger, w http.ResponseWriter, r *h
 	)
 }
 
+// IsEqual checks if an error response is equal to another.
 func (her *ErrorResponse) IsEqual(e1 *ErrorResponse) bool {
 	if !errors.Is(e1.Error, her.Error) {
 		return false
@@ -59,6 +62,7 @@ func (her *ErrorResponse) IsEqual(e1 *ErrorResponse) bool {
 	return true
 }
 
+// InternalServerError is an error that is returned when an internal server error occurs.
 type InternalServerError struct {
 	Err error
 }
@@ -71,6 +75,7 @@ func (e InternalServerError) ToErrorResponse() *ErrorResponse {
 	return NewErrorResponse(e, http.StatusInternalServerError, "internal_error", "internal error")
 }
 
+// NotFoundError is an error that is returned when a resource is not found.
 type NotFoundError struct {
 	Designation string
 }
diff --git a/response.go b/response.go
index 9f96869..4082623 100644
--- a/response.go
+++ b/response.go
@@ -6,6 +6,7 @@ import (
 	"github.com/rs/zerolog"
 )
 
+// Response is a wrapper for the response body.
 type Response struct {
 	Body           any
 	HTTPStatusCode int
diff --git a/url_params.go b/url_params.go
index e26be98..24372d8 100644
--- a/url_params.go
+++ b/url_params.go
@@ -6,8 +6,10 @@ import (
 	"net/http"
 )
 
+// NamedURLParamsGetter is the interface that is used to parse the URL parameters.
 type NamedURLParamsGetter func(ctx context.Context, key string) (string, *ErrorResponse)
 
+// MissingParamError is the error that is returned when a named URL param is missing.
 type MissingParamError struct {
 	Name string
 }
@@ -25,6 +27,7 @@ func (e MissingParamError) ToErrorResponse() *ErrorResponse {
 	}
 }
 
+// ParsingParamError is the error that is returned when a named URL param is invalid.
 type ParsingParamError struct {
 	Name  string
 	Value string
diff --git a/wrapper.go b/wrapper.go
index a60fa10..048d2c0 100644
--- a/wrapper.go
+++ b/wrapper.go
@@ -8,8 +8,10 @@ import (
 	"github.com/rs/zerolog"
 )
 
+// TypedHandler is the handler that you are actually handling the response.
 type TypedHandler func(r *http.Request) (*Response, *ErrorResponse)
 
+// Wrapper will actually do the boring work of logging an error and render the response.
 func Wrapper(
 	log zerolog.Logger,
 	f TypedHandler,