From ae289005c0a59341d203d19c17d8a66c4cb78a09 Mon Sep 17 00:00:00 2001
From: Daniel Mangum <georgedanielmangum@gmail.com>
Date: Tue, 11 Jul 2023 06:38:12 -0400
Subject: [PATCH] Document all public netctx methods

Adds documentation for all public netctx methods.

Signed-off-by: Daniel Mangum <georgedanielmangum@gmail.com>
---
 netctx/conn.go       | 10 ++++++++++
 netctx/packetconn.go | 18 ++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/netctx/conn.go b/netctx/conn.go
index a3322dc..823107c 100644
--- a/netctx/conn.go
+++ b/netctx/conn.go
@@ -62,6 +62,8 @@ func NewConn(netConn net.Conn) Conn {
 	return c
 }
 
+// ReadContext reads data from the connection.
+// Unlike net.Conn.Read(), the provided context is used to control timeout.
 func (c *conn) ReadContext(ctx context.Context, b []byte) (int, error) {
 	c.readMu.Lock()
 	defer c.readMu.Unlock()
@@ -106,6 +108,8 @@ func (c *conn) ReadContext(ctx context.Context, b []byte) (int, error) {
 	return n, err
 }
 
+// WriteContext writes data to the connection.
+// Unlike net.Conn.Write(), the provided context is used to control timeout.
 func (c *conn) WriteContext(ctx context.Context, b []byte) (int, error) {
 	c.writeMu.Lock()
 	defer c.writeMu.Unlock()
@@ -150,6 +154,9 @@ func (c *conn) WriteContext(ctx context.Context, b []byte) (int, error) {
 	return n, err
 }
 
+// Close closes the connection.
+// Any blocked ReadContext or WriteContext operations will be unblocked and
+// return errors.
 func (c *conn) Close() error {
 	err := c.nextConn.Close()
 	c.closeOnce.Do(func() {
@@ -162,14 +169,17 @@ func (c *conn) Close() error {
 	return err
 }
 
+// LocalAddr returns the local network address, if known.
 func (c *conn) LocalAddr() net.Addr {
 	return c.nextConn.LocalAddr()
 }
 
+// LocalAddr returns the local network address, if known.
 func (c *conn) RemoteAddr() net.Addr {
 	return c.nextConn.RemoteAddr()
 }
 
+// Conn returns the underlying net.Conn.
 func (c *conn) Conn() net.Conn {
 	return c.nextConn
 }
diff --git a/netctx/packetconn.go b/netctx/packetconn.go
index 1b65276..a4ce22d 100644
--- a/netctx/packetconn.go
+++ b/netctx/packetconn.go
@@ -48,6 +48,15 @@ func NewPacketConn(pconn net.PacketConn) PacketConn {
 	return p
 }
 
+// ReadFromContext reads a packet from the connection,
+// copying the payload into p. It returns the number of
+// bytes copied into p and the return address that
+// was on the packet.
+// It returns the number of bytes read (0 <= n <= len(p))
+// and any error encountered. Callers should always process
+// the n > 0 bytes returned before considering the error err.
+// Unlike net.PacketConn.ReadFrom(), the provided context is
+// used to control timeout.
 func (p *packetConn) ReadFromContext(ctx context.Context, b []byte) (int, net.Addr, error) {
 	p.readMu.Lock()
 	defer p.readMu.Unlock()
@@ -92,6 +101,10 @@ func (p *packetConn) ReadFromContext(ctx context.Context, b []byte) (int, net.Ad
 	return n, raddr, err
 }
 
+// WriteToContext writes a packet with payload p to addr.
+// Unlike net.PacketConn.WriteTo(), the provided context
+// is used to control timeout.
+// On packet-oriented connections, write timeouts are rare.
 func (p *packetConn) WriteToContext(ctx context.Context, b []byte, raddr net.Addr) (int, error) {
 	p.writeMu.Lock()
 	defer p.writeMu.Unlock()
@@ -136,6 +149,9 @@ func (p *packetConn) WriteToContext(ctx context.Context, b []byte, raddr net.Add
 	return n, err
 }
 
+// Close closes the connection.
+// Any blocked ReadFromContext or WriteToContext operations will be unblocked
+// and return errors.
 func (p *packetConn) Close() error {
 	err := p.nextConn.Close()
 	p.closeOnce.Do(func() {
@@ -148,10 +164,12 @@ func (p *packetConn) Close() error {
 	return err
 }
 
+// LocalAddr returns the local network address, if known.
 func (p *packetConn) LocalAddr() net.Addr {
 	return p.nextConn.LocalAddr()
 }
 
+// Conn returns the underlying net.PacketConn.
 func (p *packetConn) Conn() net.PacketConn {
 	return p.nextConn
 }