From 2893df64a9e604bf90077ac0eb8036e0ea44b412 Mon Sep 17 00:00:00 2001
From: Juan Martinez <martinezalonsojn@gmail.com>
Date: Fri, 27 Oct 2023 18:58:10 +0200
Subject: [PATCH] Add TCPServer documentation

---
 pkg/transport/network/tcp/server.go | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/pkg/transport/network/tcp/server.go b/pkg/transport/network/tcp/server.go
index 68b180a..fed8d60 100644
--- a/pkg/transport/network/tcp/server.go
+++ b/pkg/transport/network/tcp/server.go
@@ -7,13 +7,18 @@ import (
 	"github.com/HyperloopUPV-H8/h9-backend/pkg/abstraction"
 )
 
-type Address string
+// Address is an alias for string encoded network addresses (e.g. "127.0.0.1:4040")
+type Address = string
 
+// serverTargets are the addresses are expected to connect and their respective target name
 type serverTargets = map[Address]abstraction.TransportTarget
 
 // Assertion to check the TCPServer is a TCPSource
 var _ TCPSource = &TCPServer{}
 
+// TCPServer is a TCPSource that gets connections from clients
+//
+// TCPServer must be used as any other TCPSource.
 type TCPServer struct {
 	name         abstraction.TransportTarget
 	targets      serverTargets
@@ -23,6 +28,8 @@ type TCPServer struct {
 	onError      errorCallback
 }
 
+// NewServer creates a new TCPServer with the given name, local address and target connections.
+// It returns a non nil error if it fails to resolve the local address or when the listener creation fails.
 func NewServer(name abstraction.TransportTarget, laddr string, targets serverTargets) (*TCPServer, error) {
 	localAddr, err := net.ResolveTCPAddr("tcp", laddr)
 	if err != nil {
@@ -42,23 +49,35 @@ func NewServer(name abstraction.TransportTarget, laddr string, targets serverTar
 	}, nil
 }
 
+// SetKeepalive sets the keepalive that will be applied to the connections established
 func (server *TCPServer) SetKeepalive(keepalive time.Duration) {
 	server.keepalive = keepalive
 }
 
+// SetOnConnection registers the callback that will be used when a connection is made
 func (server *TCPServer) SetOnConnection(callback connectionCallback) {
 	server.onConnection = callback
 }
 
+// SetOnError registers the callback that will be used when an error making the connection occurs.
 func (server *TCPServer) SetOnError(callback errorCallback) {
 	server.onError = callback
 }
 
+// accept result is an auxiliary struct to pass the results of listener.Accept through a channel
 type acceptResult struct {
 	conn *net.TCPConn
 	err  error
 }
 
+// Run starts the TCPServer.
+//
+// When a conneciton is established, it first checks if it's valid, then configures it and lastly
+// notifies of the connection with the OnConnection callback.
+//
+// Callers should make sure the OnConnection and the OnError callbacks are provided before calling Run.
+//
+// The server execution can be stopped by sending a message to the cancel channel.
 func (server *TCPServer) Run(cancel <-chan struct{}) {
 	defer server.listener.Close()
 	for {
@@ -101,6 +120,7 @@ func (server *TCPServer) Run(cancel <-chan struct{}) {
 	}
 }
 
+// configureConn is a helper to apply all configuration to a connection.
 func (server *TCPServer) configureConn(conn *net.TCPConn) error {
 	err := conn.SetKeepAlive(server.keepalive > 0)
 	if err != nil {