docs(ax): clarify public api examples

Co-Authored-By: Virgil <virgil@lethean.io>

api/router.go

@@ -78,7 +78,7 @@ type ResultsResponse struct {
 	Best        [10]uint64 `json:"best"`
 }
 
-// RegisterRoutes registers the proxy monitoring routes on a HTTP router.
+// RegisterRoutes mounts `/1/summary`, `/1/workers`, and `/1/miners` on a router.
 //
 //	api.RegisterRoutes(http.NewServeMux(), p)
 func RegisterRoutes(router Router, proxyValue *proxy.Proxy) {

config_runtime.go

@@ -8,7 +8,7 @@ import (
 	"time"
 )
 
-// LoadConfig reads and unmarshals a JSON config file.
+// LoadConfig reads `config.json` and returns a validated `Config`.
 //
 //	cfg, errorValue := proxy.LoadConfig("config.json")
 func LoadConfig(path string) (*Config, error) {
@@ -30,7 +30,7 @@ func LoadConfig(path string) (*Config, error) {
 	return config, nil
 }
 
-// Validate checks required fields.
+// Validate checks that `bind` and `pools` are present and every enabled pool has a URL.
 //
 //	if errorValue := cfg.Validate(); errorValue != nil { return errorValue }
 func (c *Config) Validate() error {
@@ -53,7 +53,7 @@ func (c *Config) Validate() error {
 	return nil
 }
 
-// NewConfigWatcher builds a polling watcher for the config file.
+// NewConfigWatcher watches `config.json` and calls `p.Reload(cfg)` on change.
 //
 //	w := proxy.NewConfigWatcher("config.json", func(cfg *proxy.Config) { p.Reload(cfg) })
 func NewConfigWatcher(path string, onChange func(*Config)) *ConfigWatcher {
@@ -64,7 +64,7 @@ func NewConfigWatcher(path string, onChange func(*Config)) *ConfigWatcher {
 	}
 }
 
-// Start begins the polling goroutine.
+// Start begins 1-second polling for `config.json`.
 //
 //	w.Start()
 func (w *ConfigWatcher) Start() {
@@ -103,7 +103,7 @@ func (w *ConfigWatcher) Start() {
 	}()
 }
 
-// Stop ends the polling goroutine cleanly.
+// Stop ends polling so the watcher can be shut down with `p.Stop()`.
 //
 //	w.Stop()
 func (w *ConfigWatcher) Stop() {

log/access.go

@@ -13,31 +13,26 @@ import (
 	"dappco.re/go/core/proxy"
 )
 
-// AccessLog writes connection lifecycle lines to an append-only text file.
+// AccessLog writes one CONNECT line on login and one CLOSE line on disconnect.
 //
-// Line format (connect): 2026-04-04T12:00:00Z CONNECT  <ip>  <user>  <agent>
-// Line format (close):   2026-04-04T12:00:00Z CLOSE    <ip>  <user>  rx=<bytes>  tx=<bytes>
-//
-//	al, result := log.NewAccessLog("/var/log/proxy-access.log")
+//	al := log.NewAccessLog("/var/log/proxy-access.log")
 //	bus.Subscribe(proxy.EventLogin, al.OnLogin)
 //	bus.Subscribe(proxy.EventClose, al.OnClose)
 type AccessLog struct {
-	path string
-	mu   sync.Mutex
-	// f is opened append-only on first write; nil until first event.
-	// Uses core.File for I/O abstraction.
+	path   string
+	mu     sync.Mutex
 	f      *os.File
 	closed bool
 }
 
-// NewAccessLog stores the destination path and lazily opens it on first write.
+// NewAccessLog returns a lazy append-only logger for a single path.
 //
 //	al := log.NewAccessLog("/var/log/proxy-access.log")
 func NewAccessLog(path string) *AccessLog {
 	return &AccessLog{path: path}
 }
 
-// OnLogin writes a CONNECT line. Called synchronously from the event bus.
+// OnLogin writes `2026-04-04T12:00:00Z CONNECT  10.0.0.1  WALLET  XMRig/6.21.0`.
 //
 //	al.OnLogin(proxy.Event{Miner: miner})
 func (l *AccessLog) OnLogin(event proxy.Event) {
@@ -54,7 +49,7 @@ func (l *AccessLog) OnLogin(event proxy.Event) {
 	l.writeLine(line)
 }
 
-// OnClose writes a CLOSE line with byte counts.
+// OnClose writes `2026-04-04T12:00:00Z CLOSE    10.0.0.1  WALLET  rx=512  tx=4096`.
 //
 //	al.OnClose(proxy.Event{Miner: miner})
 func (l *AccessLog) OnClose(event proxy.Event) {

log/share.go

@@ -9,31 +9,26 @@ import (
 	"dappco.re/go/core/proxy"
 )
 
-// ShareLog writes share result lines to an append-only text file.
-//
-// Line format (accept): 2026-04-04T12:00:00Z ACCEPT  <user>  diff=<diff>  latency=<ms>ms
-// Line format (reject): 2026-04-04T12:00:00Z REJECT  <user>  reason="<message>"
+// ShareLog writes one ACCEPT line for accepted shares and one REJECT line for errors.
 //
 //	sl := log.NewShareLog("/var/log/proxy-shares.log")
 //	bus.Subscribe(proxy.EventAccept, sl.OnAccept)
 //	bus.Subscribe(proxy.EventReject, sl.OnReject)
 type ShareLog struct {
-	path string
-	mu   sync.Mutex
-	// f is opened append-only on first write; nil until first event.
-	// Uses core.File for I/O abstraction.
+	path   string
+	mu     sync.Mutex
 	f      *os.File
 	closed bool
 }
 
-// NewShareLog stores the destination path and lazily opens it on first write.
+// NewShareLog returns a lazy append-only logger for share outcomes.
 //
 //	sl := log.NewShareLog("/var/log/proxy-shares.log")
 func NewShareLog(path string) *ShareLog {
 	return &ShareLog{path: path}
 }
 
-// OnAccept writes an ACCEPT line.
+// OnAccept writes `2026-04-04T12:00:00Z ACCEPT  WALLET  diff=100000  latency=82ms`.
 //
 //	sl.OnAccept(proxy.Event{Miner: miner, Diff: 100000})
 func (l *ShareLog) OnAccept(event proxy.Event) {
@@ -50,7 +45,7 @@ func (l *ShareLog) OnAccept(event proxy.Event) {
 	l.writeLine(line)
 }
 
-// OnReject writes a REJECT line with the rejection reason.
+// OnReject writes `2026-04-04T12:00:00Z REJECT  WALLET  reason="Low difficulty share"`.
 //
 //	sl.OnReject(proxy.Event{Miner: miner, Error: "Low difficulty share"})
 func (l *ShareLog) OnReject(event proxy.Event) {

proxy_runtime.go

@@ -12,7 +12,7 @@ type splitterShutdown interface {
 	Disconnect()
 }
 
-// New creates and wires all subsystems but does not start the tick loop or TCP listeners.
+// New wires the proxy and returns a ready-to-start instance.
 //
 //	p, errorValue := proxy.New(config)
 func New(config *Config) (*Proxy, error) {
@@ -98,7 +98,7 @@ func New(config *Config) (*Proxy, error) {
 	return proxyInstance, nil
 }
 
-// Start begins the TCP listener(s), pool connections, and tick loop.
+// Start connects the pool, opens listeners, and blocks until `Stop()`.
 //
 //	p.Start()
 func (p *Proxy) Start() {
@@ -171,7 +171,7 @@ func noopSplitterFactory(cfg *Config, events *EventBus) Splitter {
 	return noopSplitter{}
 }
 
-// Stop shuts down all subsystems cleanly.
+// Stop closes listeners, log files, watcher, miners, and pool connections.
 //
 //	p.Stop()
 func (p *Proxy) Stop() {

runtime_support.go

@@ -6,7 +6,7 @@ import (
 	"time"
 )
 
-// NewRateLimiter allocates a per-IP token bucket limiter.
+// NewRateLimiter creates a per-IP limiter, for example:
 //
 //	rl := proxy.NewRateLimiter(cfg.RateLimit)
 func NewRateLimiter(config RateLimit) *RateLimiter {
@@ -17,7 +17,7 @@ func NewRateLimiter(config RateLimit) *RateLimiter {
 	}
 }
 
-// SetConfig replaces the active rate-limit settings.
+// SetConfig swaps in a live reload value such as `proxy.RateLimit{MaxConnectionsPerMinute: 30}`.
 //
 //	rl.SetConfig(proxy.RateLimit{MaxConnectionsPerMinute: 30, BanDurationSeconds: 300})
 func (rateLimiter *RateLimiter) SetConfig(config RateLimit) {
@@ -146,7 +146,7 @@ func (customDiff *CustomDiff) SetGlobalDiff(globalDiff uint64) {
 	customDiff.mu.Unlock()
 }
 
-// OnLogin parses miner.User for a "+{number}" suffix and sets miner.CustomDiff.
+// OnLogin parses `WALLET+50000` into `WALLET` and `50000`.
 //
 //	cd.OnLogin(proxy.Event{Miner: miner})
 func (customDiff *CustomDiff) OnLogin(event Event) {

server_runtime.go

@@ -7,7 +7,7 @@ import (
 	"strconv"
 )
 
-// NewServer binds one miner-facing TCP listener.
+// NewServer opens `0.0.0.0:3333` and prepares the accept loop.
 //
 //	srv, errorValue := proxy.NewServer(bindAddress, nil, rateLimiter, onAccept)
 func NewServer(bindAddress BindAddr, tlsConfig *tls.Config, rateLimiter *RateLimiter, onAccept func(net.Conn, uint16)) (*Server, error) {
@@ -27,7 +27,7 @@ func NewServer(bindAddress BindAddr, tlsConfig *tls.Config, rateLimiter *RateLim
 	}, nil
 }
 
-// Start begins accepting connections in a goroutine.
+// Start accepts miners in a background goroutine.
 //
 //	srv.Start()
 func (server *Server) Start() {
@@ -65,7 +65,7 @@ func (server *Server) Start() {
 	}()
 }
 
-// Stop closes the listener.
+// Stop closes `0.0.0.0:3333` without forcing existing sockets shut.
 //
 //	srv.Stop()
 func (server *Server) Stop() {