docs(proxy): align public comments with AX

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

api/router.go

@@ -1,4 +1,4 @@
-// Package api mounts the three monitoring endpoints on an HTTP mux.
+// Package api mounts the monitoring endpoints on an HTTP mux.
 //
 //	mux := http.NewServeMux()
 //	api.RegisterRoutes(mux, p)
@@ -20,7 +20,8 @@ type RouteRegistrar interface {
 }
 
 // mux := http.NewServeMux()
-// api.RegisterRoutes(mux, p) // GET /1/summary, /1/workers, /1/miners
+// api.RegisterRoutes(mux, p)
+// GET /1/summary, /1/workers, and /1/miners
 func RegisterRoutes(router RouteRegistrar, p *proxy.Proxy) {
 	if router == nil || p == nil {
 		return

core_impl.go

@@ -17,7 +17,12 @@ import (
 	"time"
 )
 
-// Result is a small success/error carrier used by constructors and loaders.
+// Result is the success/error carrier used by constructors and loaders.
+//
+//	cfg, result := proxy.LoadConfig("config.json")
+//	if !result.OK {
+//	    return result.Error
+//	}
 type Result struct {
 	OK    bool
 	Error error
@@ -34,7 +39,7 @@ func newErrorResult(err error) Result {
 var splitterFactoriesMu sync.RWMutex
 var splitterFactoriesByMode = map[string]func(*Config, *EventBus) Splitter{}
 
-// Register a mode-specific splitter constructor.
+// RegisterSplitterFactory installs the constructor used for one proxy mode.
 //
 //	proxy.RegisterSplitterFactory("simple", func(cfg *proxy.Config, bus *proxy.EventBus) proxy.Splitter {
 //	    return simple.NewSimpleSplitter(cfg, bus, nil)

pool/client.go

@@ -1,7 +1,9 @@
-// Package pool implements the outbound stratum pool client and failover strategy.
+// Package pool implements the outbound pool client and failover strategy.
 //
-//	client := pool.NewStratumClient(poolCfg, listener)
-//	client.Connect()
+//	client := pool.NewStratumClient(proxy.PoolConfig{URL: "pool.example:3333", User: "WALLET", Pass: "x"}, listener)
+//	if result := client.Connect(); result.OK {
+//	    client.Login()
+//	}
 package pool
 
 import (
@@ -12,8 +14,11 @@ import (
 	"dappco.re/go/proxy"
 )
 
-// client := NewStratumClient(poolCfg, listener)
-// client.Connect()
+// client := pool.NewStratumClient(poolCfg, listener)
+//
+//	if result := client.Connect(); result.OK {
+//	    client.Login()
+//	}
 type StratumClient struct {
 	config     proxy.PoolConfig
 	listener   StratumListener

pool/impl.go

@@ -19,7 +19,7 @@ import (
 
 // NewStrategyFactory creates a StrategyFactory for the supplied config.
 //
-//	factory := pool.NewStrategyFactory(cfg)
+//	factory := pool.NewStrategyFactory(&proxy.Config{Pools: []proxy.PoolConfig{{URL: "pool.example:3333", Enabled: true}}})
 //	strategy := factory(listener)
 func NewStrategyFactory(config *proxy.Config) StrategyFactory {
 	return func(listener StratumListener) Strategy {
@@ -27,8 +27,11 @@ func NewStrategyFactory(config *proxy.Config) StrategyFactory {
 	}
 }
 
-// client := pool.NewStratumClient(poolCfg, listener)
-// client.Connect()
+// client := pool.NewStratumClient(proxy.PoolConfig{URL: "pool.example:3333", User: "WALLET", Pass: "x"}, listener)
+//
+//	if result := client.Connect(); result.OK {
+//	    client.Login()
+//	}
 func NewStratumClient(poolConfig proxy.PoolConfig, listener StratumListener) *StratumClient {
 	return &StratumClient{
 		config:   poolConfig,
@@ -47,7 +50,7 @@ func (c *StratumClient) IsActive() bool {
 	return c.active
 }
 
-// client.Connect()
+// result := client.Connect()
 func (c *StratumClient) Connect() proxy.Result {
 	if c == nil {
 		return proxy.Result{OK: false, Error: errors.New("client is nil")}
@@ -93,6 +96,8 @@ func (c *StratumClient) Connect() proxy.Result {
 }
 
 // client.Login()
+//
+// A login reply with a job triggers `OnJob` immediately.
 func (c *StratumClient) Login() {
 	if c == nil || c.conn == nil {
 		return
@@ -116,7 +121,7 @@ func (c *StratumClient) Login() {
 	_ = c.writeJSON(req)
 }
 
-// seq := client.Submit(jobID, "deadbeef", "HASH64HEX", "cn/r")
+// seq := client.Submit("job-1", "deadbeef", "HASH64HEX", "cn/r")
 func (c *StratumClient) Submit(jobID, nonce, result, algo string) int64 {
 	if c == nil {
 		return 0

pool/strategy.go

@@ -7,10 +7,11 @@ import (
 )
 
 // FailoverStrategy wraps an ordered slice of PoolConfig entries.
-// It connects to the first enabled pool and fails over in order on error.
-// On reconnect it always retries from the primary first.
 //
-//	strategy := pool.NewFailoverStrategy(cfg.Pools, listener, cfg)
+//	strategy := pool.NewFailoverStrategy([]proxy.PoolConfig{
+//	    {URL: "primary.example:3333", Enabled: true},
+//	    {URL: "backup.example:3333", Enabled: true},
+//	}, listener, cfg)
 //	strategy.Connect()
 type FailoverStrategy struct {
 	pools    []proxy.PoolConfig
@@ -23,8 +24,6 @@ type FailoverStrategy struct {
 }
 
 // StrategyFactory creates a FailoverStrategy for a given StratumListener.
-// Splitters use it to create one upstream strategy per mapper without importing
-// the pool wiring directly.
 //
 //	factory := pool.NewStrategyFactory(cfg)
 //	strategy := factory(listener)

proxy.go

@@ -1,13 +1,10 @@
-// Package proxy is a CryptoNote stratum mining proxy library.
-//
-// It accepts miner connections over TCP (optionally TLS), splits the 32-bit nonce
-// space across up to 256 simultaneous miners per upstream pool connection (NiceHash
-// mode), and presents a small monitoring API.
-//
-// Full specification: docs/RFC.md
+// Package proxy is the mining proxy library.
 //
+//	cfg := &proxy.Config{Mode: "nicehash", Bind: []proxy.BindAddr{{Host: "0.0.0.0", Port: 3333}}, Pools: []proxy.PoolConfig{{URL: "pool.example:3333", Enabled: true}}, Workers: proxy.WorkersByRigID}
 //	p, result := proxy.New(cfg)
-//	if result.OK { p.Start() }
+//	if result.OK {
+//	    p.Start()
+//	}
 package proxy
 
 import (