adjust comments

Author: xtaci

autotune.go

@@ -30,7 +30,7 @@ type pulse struct {
 	seq uint32 // sequence of the signal
 }
 
-// autoTune object
+// autoTune object to detect pulses in a signal
 type autoTune struct {
 	pulses [maxAutoTuneSamples]pulse
 }

batchconn.go

@@ -28,6 +28,7 @@ const (
 	batchSize = 16
 )
 
+// batchConn defines the interface used in batch IO
 type batchConn interface {
 	WriteBatch(ms []ipv4.Message, flags int) (int, error)
 	ReadBatch(ms []ipv4.Message, flags int) (int, error)

crypt.go

@@ -42,6 +42,11 @@ import (
 )
 
 var (
+	// a defined initial vector
+	// https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Initialization_vector_.28IV.29
+	// https://en.wikipedia.org/wiki/Initialization_vector
+	// actually initial vector is not used in this package, we prepend a random nonce to each outgoing packets.
+	// though IV is fixed, the first 8 bytes of the encrypted data is always random.
 	initialVector = []byte{167, 115, 79, 156, 18, 172, 27, 1, 164, 21, 242, 193, 252, 120, 230, 107}
 	saltxor       = `sH3CIVoF#rWLtJo6`
 )
@@ -459,6 +464,7 @@ func decrypt8(block cipher.Block, dst, src, buf []byte) {
 	ptr_tbl := (*uint64)(unsafe.Pointer(&tbl[0]))
 	ptr_next := (*uint64)(unsafe.Pointer(&next[0]))
 
+	// loop unrolling to relieve data dependency
 	for i := 0; i < repeat; i++ {
 		s := src[base:][0:64]
 		d := dst[base:][0:64]
@@ -545,6 +551,8 @@ func decrypt16(block cipher.Block, dst, src, buf []byte) {
 	base := 0
 	repeat := n / 8
 	left := n % 8
+
+	// loop unrolling to relieve data dependency
 	for i := 0; i < repeat; i++ {
 		s := src[base:][0:128]
 		d := dst[base:][0:128]

entropy.go

@@ -31,6 +31,8 @@ import (
 )
 
 // Entropy defines a entropy source
+//
+//	Entropy in this file generate random bits for the first 16-bytes of each packets.
 type Entropy interface {
 	Init()
 	Fill(nonce []byte)

fec.go

@@ -112,6 +112,7 @@ func (dec *fecDecoder) decode(in fecPacket) (recovered [][]byte) {
 		}
 	}
 
+	// if signal is out-of-sync, try to detect the pattern in the signal
 	if dec.shouldTune {
 		autoDS := dec.autoTune.FindPeriod(true)
 		autoPS := dec.autoTune.FindPeriod(false)

readloop.go

@@ -28,6 +28,7 @@ import (
 	"github.com/pkg/errors"
 )
 
+// defaultReadLoop is the standard procedure for reading from a connection
 func (s *UDPSession) defaultReadLoop() {
 	buf := make([]byte, mtuLimit)
 	var src string
@@ -48,6 +49,7 @@ func (s *UDPSession) defaultReadLoop() {
 	}
 }
 
+// defaultReadLoop is the standard procedure for reading and accepting connections on a listener
 func (l *Listener) defaultMonitor() {
 	buf := make([]byte, mtuLimit)
 	for {

readloop_generic.go

@@ -21,7 +21,6 @@
 // SOFTWARE.
 
 //go:build !linux
-// +build !linux
 
 package kcp
 

readloop_linux.go

@@ -35,7 +35,7 @@ import (
 	"golang.org/x/net/ipv6"
 )
 
-// the read loop for a client session
+// readLoop is the optimized version of readLoop for linux utilizing recvmmsg syscall
 func (s *UDPSession) readLoop() {
 	// default version
 	if s.xconn == nil {
@@ -83,7 +83,7 @@ func (s *UDPSession) readLoop() {
 	}
 }
 
-// monitor incoming data for all connections of server
+// monitor is the optimized version of monitor for linux utilizing recvmmsg syscall
 func (l *Listener) monitor() {
 	var xconn batchConn
 	if _, ok := l.conn.(*net.UDPConn); ok {

timedsched.go

@@ -81,6 +81,7 @@ func NewTimedSched(parallel int) *TimedSched {
 	return ts
 }
 
+// sched is a goroutine to schedule and execute timed tasks.
 func (ts *TimedSched) sched() {
 	var tasks timedFuncHeap
 	timer := time.NewTimer(0)
@@ -119,6 +120,7 @@ func (ts *TimedSched) sched() {
 	}
 }
 
+// prepend is the front desk goroutine to register tasks
 func (ts *TimedSched) prepend() {
 	var tasks []timedFunc
 	for {

tx.go

@@ -29,6 +29,7 @@ import (
 	"golang.org/x/net/ipv4"
 )
 
+// defaultTx is the default procedure to transmit data
 func (s *UDPSession) defaultTx(txqueue []ipv4.Message) {
 	nbytes := 0
 	npkts := 0

tx_generic.go

@@ -21,7 +21,6 @@
 // SOFTWARE.
 
 //go:build !linux
-// +build !linux
 
 package kcp
 

tx_linux.go

@@ -21,7 +21,6 @@
 // SOFTWARE.
 
 //go:build linux
-// +build linux
 
 package kcp
 
@@ -34,6 +33,7 @@ import (
 	"golang.org/x/net/ipv4"
 )
 
+// tx is the optimized procedure to transmit packets utilizing the linux sendmmsg system call
 func (s *UDPSession) tx(txqueue []ipv4.Message) {
 	// default version
 	if s.xconn == nil || s.xconnWriteError != nil {