improve documentation

backend/internal/web/adapters/actions.go

@@ -10,7 +10,18 @@ import (
 // It decodes the request body into a value of type T and passes it to the function f.
 // The function f is expected to return a value of type Y and an error.
 //
-// Note: Action differs from Query in that it decodes the request body.
+// Example:
+//
+//	type Body struct {
+//	    Foo string `json:"foo"`
+//	}
+//
+//	fn := func(ctx context.Context, b Body) (any, error) {
+//	    // do something with b
+//	    return nil, nil
+//	}
+//
+// r.Post("/foo", adapters.Action(fn, http.StatusCreated))
 func Action[T any, Y any](f AdapterFunc[T, Y], ok int) server.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) error {
 		v, err := decode[T](r)
@@ -28,6 +39,19 @@ func Action[T any, Y any](f AdapterFunc[T, Y], ok int) server.HandlerFunc {
 }
 
 // ActionID functions the same as Action, but it also decodes a UUID from the URL path.
+//
+// Example:
+//
+//	type Body struct {
+//	    Foo string `json:"foo"`
+//	}
+//
+//	fn := func(ctx context.Context, ID uuid.UUID, b Body) (any, error) {
+//	    // do something with ID and b
+//	    return nil, nil
+//	}
+//
+//	r.Post("/foo/{id}", adapters.ActionID(fn, http.StatusCreated))
 func ActionID[T any, Y any](param string, f IDFunc[T, Y], ok int) server.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) error {
 		ID, err := routeUUID(r, param)

backend/internal/web/adapters/adapters.go

@@ -1,4 +1,3 @@
-// Package adapters provides functions to adapt functions to the server.Handler interface.
 package adapters
 
 import (

backend/internal/web/adapters/command.go

@@ -11,6 +11,18 @@ import (
 type CommandFunc[T any] func(context.Context) (T, error)
 type CommandIDFunc[T any] func(context.Context, uuid.UUID) (T, error)
 
+// Command is an HandlerAdapter that returns a server.HandlerFunc that
+// The command adapters are used to handle commands that do not accept a body
+// or a query. You can think of them as a way to handle RPC style Rest Endpoints.
+//
+// Example:
+//
+//	fn := func(ctx context.Context) (interface{}, error) {
+//		// do something
+//		return nil, nil
+//	}
+//
+//  r.Get("/foo", adapters.Command(fn, http.NoContent))
 func Command[T any](f CommandFunc[T], ok int) server.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) error {
 		res, err := f(r.Context())
@@ -22,6 +34,17 @@ func Command[T any](f CommandFunc[T], ok int) server.HandlerFunc {
 	}
 }
 
+// CommandID is the same as the Command adapter but it accepts a UUID as a parameter
+// in the URL. The parameter name is passed as the first argument.
+//
+// Example:
+//
+//	fn := func(ctx context.Context, id uuid.UUID) (interface{}, error) {
+//		// do something
+//		return nil, nil
+//	}
+//
+//	r.Get("/foo/{id}", adapters.CommandID("id", fn, http.NoContent))
 func CommandID[T any](param string, f CommandIDFunc[T], ok int) server.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) error {
 		ID, err := routeUUID(r, param)

backend/internal/web/adapters/doc.go

@@ -0,0 +1,9 @@
+/*
+Package adapters offers common adapters for turing regular functions into HTTP Handlers
+There are three types of adapters
+
+  - Query adapters
+  - Action adapters
+  - Command adapters
+*/
+package adapters

backend/internal/web/adapters/query.go

@@ -7,6 +7,19 @@ import (
 )
 
 // Query is a server.Handler that decodes a query from the request and calls the provided function.
+//
+// Example:
+//
+//	type Query struct {
+//	    Foo string `schema:"foo"`
+//	}
+//
+//	fn := func(ctx context.Context, q Query) (any, error) {
+//	    // do something with q
+//		return nil, nil
+//	}
+//
+//	r.Get("/foo", adapters.Query(fn, http.StatusOK))
 func Query[T any, Y any](f AdapterFunc[T, Y], ok int) server.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) error {
 		q, err := decodeQuery[T](r)
@@ -24,6 +37,19 @@ func Query[T any, Y any](f AdapterFunc[T, Y], ok int) server.HandlerFunc {
 }
 
 // QueryID is a server.Handler that decodes a query and an ID from the request and calls the provided function.
+//
+// Example:
+//
+//	type Query struct {
+//	    Foo string `schema:"foo"`
+//	}
+//
+//	fn := func(ctx context.Context, ID uuid.UUID, q Query) (any, error) {
+//	    // do something with ID and q
+//		return nil, nil
+//	}
+//
+//	r.Get("/foo/{id}", adapters.QueryID(fn, http.StatusOK))
 func QueryID[T any, Y any](param string, f IDFunc[T, Y], ok int) server.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) error {
 		ID, err := routeUUID(r, param)