From 68edd770d81c31c238cd1a93409f4f5f526ca67c Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Thu, 2 Apr 2026 00:03:10 +0000
Subject: [PATCH] docs(api): add ax usage examples

Co-Authored-By: Virgil <virgil@lethean.io>
---
 api.go     | 34 ++++++++++++++++++++++++++++++++++
 options.go | 12 ++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/api.go b/api.go
index e21cc16..c5161de 100644
--- a/api.go
+++ b/api.go
@@ -25,6 +25,14 @@ const defaultAddr = ":8080"
 const shutdownTimeout = 10 * time.Second
 
 // Engine is the central API server managing route groups and middleware.
+//
+// Example:
+//
+//	engine, err := api.New(api.WithAddr(":8081"))
+//	if err != nil {
+//		panic(err)
+//	}
+//	_ = engine.Handler()
 type Engine struct {
 	addr                           string
 	groups                         []RouteGroup
@@ -51,6 +59,13 @@ type Engine struct {
 
 // New creates an Engine with the given options.
 // The default listen address is ":8080".
+//
+// Example:
+//
+//	engine, err := api.New(api.WithAddr(":8081"), api.WithResponseMeta())
+//	if err != nil {
+//		panic(err)
+//	}
 func New(opts ...Option) (*Engine, error) {
 	e := &Engine{
 		addr: defaultAddr,
@@ -62,6 +77,11 @@ func New(opts ...Option) (*Engine, error) {
 }
 
 // Addr returns the configured listen address.
+//
+// Example:
+//
+//	engine, _ := api.New(api.WithAddr(":9090"))
+//	addr := engine.Addr()
 func (e *Engine) Addr() string {
 	return e.addr
 }
@@ -78,6 +98,10 @@ func (e *Engine) GroupsIter() iter.Seq[RouteGroup] {
 }
 
 // Register adds a route group to the engine.
+//
+// Example:
+//
+//	engine.Register(myGroup)
 func (e *Engine) Register(group RouteGroup) {
 	if isNilRouteGroup(group) {
 		return
@@ -115,12 +139,22 @@ func (e *Engine) ChannelsIter() iter.Seq[string] {
 
 // Handler builds the Gin engine and returns it as an http.Handler.
 // Each call produces a fresh handler reflecting the current set of groups.
+//
+// Example:
+//
+//	handler := engine.Handler()
 func (e *Engine) Handler() http.Handler {
 	return e.build()
 }
 
 // Serve starts the HTTP server and blocks until the context is cancelled,
 // then performs a graceful shutdown allowing in-flight requests to complete.
+//
+// Example:
+//
+//	ctx, cancel := context.WithCancel(context.Background())
+//	defer cancel()
+//	_ = engine.Serve(ctx)
 func (e *Engine) Serve(ctx context.Context) error {
 	srv := &http.Server{
 		Addr:    e.addr,
diff --git a/options.go b/options.go
index c75b304..a1b6af5 100644
--- a/options.go
+++ b/options.go
@@ -29,6 +29,10 @@ import (
 type Option func(*Engine)
 
 // WithAddr sets the listen address for the server.
+//
+// Example:
+//
+//	api.New(api.WithAddr(":8443"))
 func WithAddr(addr string) Option {
 	return func(e *Engine) {
 		e.addr = addr
@@ -56,6 +60,10 @@ func WithRequestID() Option {
 // It preserves any existing pagination metadata and merges in request_id
 // and duration when available from the request context. Combine it with
 // WithRequestID() to populate both fields automatically.
+//
+// Example:
+//
+//	api.New(api.WithRequestID(), api.WithResponseMeta())
 func WithResponseMeta() Option {
 	return func(e *Engine) {
 		e.middlewares = append(e.middlewares, responseMetaMiddleware())
@@ -103,6 +111,10 @@ func WithStatic(urlPrefix, root string) Option {
 
 // WithWSHandler registers a WebSocket handler at GET /ws.
 // Typically this wraps a go-ws Hub.Handler().
+//
+// Example:
+//
+//	api.New(api.WithWSHandler(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {})))
 func WithWSHandler(h http.Handler) Option {
 	return func(e *Engine) {
 		e.wsHandler = h