docs: add code comments

inet.go

@@ -13,27 +13,53 @@ import (
 )
 
 var (
-	IPV4zero        = net.IPv4zero
+
+	// IPV4zero is an IPv4 address representing the zero value (0.0.0.0).
+	IPV4zero = net.IPv4zero
+
+	// IPV6unspecified is an IPv6 address representing the unspecified value (::).
 	IPV6unspecified = net.IPv6unspecified
-	IPv4LoopBack    = net.IPv4(127, 0, 0, 1)
-	IPv6LoopBack    = net.IPv6loopback
+
+	// IPv4LoopBack is an IPv4 address representing the loopback address (127.0.0.1).
+	IPv4LoopBack = net.IPv4(127, 0, 0, 1)
+
+	// IPv6LoopBack is an IPv6 address representing the loopback address (::).
+	IPv6LoopBack = net.IPv6loopback
 )
 
+// IP represents an IP address.
+// It is a type alias for the net.IP type.
 type IP = net.IP
+
+// IPAddr represents a network address of type IP.
+// It is a type alias for the net.IPAddr type.
 type IPAddr = net.IPAddr
+
+// TCPAddr represents the address of a TCP endpoint.
+// It is a type alias for the net.TCPAddr type.
 type TCPAddr = net.TCPAddr
+
+// UDPAddr represents the address of a UDP endpoint.
+// It is a type alias for the net.UDPAddr type.
 type UDPAddr = net.UDPAddr
 
+// SCTPAddr represents the address of a SCTP endpoint.
+// It contains the IP address, port number, and IPv6 zone.
 type SCTPAddr struct {
 	IP   net.IP
 	Port int
 	Zone string
 }
 
+// Network returns the network name "sctp"
 func (a *SCTPAddr) Network() string {
 	return "sctp"
 }
 
+// String returns the string representation of the SCTPAddr.
+// It returns "<nil>" if the SCTPAddr is nil.
+// Otherwise, it combines the IP address, IPv6 zone (if present), and port number
+// using the net.JoinHostPort function and returns the resulting string.
 func (a *SCTPAddr) String() string {
 	if a == nil {
 		return "<nil>"
@@ -49,10 +75,20 @@ func (a *SCTPAddr) String() string {
 }
 
 var (
+	// TCPAddrFromAddrPort refers to the net.TCPAddrFromAddrPort function
+	// It returns addr as a [TCPAddr]. If addr.IsValid() is false,
+	// then the returned TCPAddr will contain a nil IP field, indicating an
+	// address family-agnostic unspecified address.
 	TCPAddrFromAddrPort = net.TCPAddrFromAddrPort
+
+	// UDPAddrFromAddrPort refers to the net.UDPAddrFromAddrPort function
+	// It returns addr as a UDPAddr. If addr.IsValid() is false,
+	// then the returned UDPAddr will contain a nil IP field, indicating an
+	// address family-agnostic unspecified address.
 	UDPAddrFromAddrPort = net.UDPAddrFromAddrPort
 )
 
+// SCTPAddrFromAddrPort returns a new SCTPAddr based on the given netip.AddrPort.
 func SCTPAddrFromAddrPort(addr netip.AddrPort) *SCTPAddr {
 	return &SCTPAddr{
 		IP:   addr.Addr().AsSlice(),
@@ -62,11 +98,23 @@ func SCTPAddrFromAddrPort(addr netip.AddrPort) *SCTPAddr {
 }
 
 var (
-	ResolveIPAddr  = net.ResolveIPAddr
+	// ResolveIPAddr refers to the net.ResolveIPAddr function
+	// It returns an address of IP end point.
+	ResolveIPAddr = net.ResolveIPAddr
+
+	// ResolveTCPAddr refers to the net.ResolveTCPAddr function.
+	// It returns a TCPAddr struct that contains IP and port information.
 	ResolveTCPAddr = net.ResolveTCPAddr
+
+	// ResolveUDPAddr refers to the net.ResolveUDPAddr function.
+	// It takes a network type and a string representation of the address and returns a
+	// UDPAddr struct that contains the IP and port information.
 	ResolveUDPAddr = net.ResolveUDPAddr
 )
 
+// ResolveSCTPAddr resolves the SCTP network address of the given network and address string.
+// It returns a new SCTPAddr based on the resolved address and network.
+// Possible network values are "sctp", "sctp4", and "sctp6".
 func ResolveSCTPAddr(network, address string) (*SCTPAddr, error) {
 	switch network {
 	case "sctp", "sctp4", "sctp6":
@@ -114,18 +162,25 @@ func ResolveSCTPAddr(network, address string) (*SCTPAddr, error) {
 	return addr4, nil
 }
 
+// IPAddrFromTCPAddr returns a new IPAddr based on the given TCPAddr.
 func IPAddrFromTCPAddr(addr *TCPAddr) *IPAddr {
 	return &IPAddr{IP: addr.IP, Zone: addr.Zone}
 }
 
+// IPAddrFromUDPAddr returns a new IPAddr based on the given UDPAddr.
+// It sets the IP and Zone fields of the IPAddr with the values from the UDPAddr.
 func IPAddrFromUDPAddr(addr *UDPAddr) *IPAddr {
 	return &IPAddr{IP: addr.IP, Zone: addr.Zone}
 }
 
+// IPAddrFromSCTPAddr returns a new IPAddr based on the given SCTPAddr.
 func IPAddrFromSCTPAddr(addr *SCTPAddr) *IPAddr {
 	return &IPAddr{IP: addr.IP, Zone: addr.Zone}
 }
 
+// IP4AddressToBytes converts an IPv4 address to a byte array.
+// If the given IP address is not an IPv4 address, it returns an empty byte array.
+// The byte array contains the four octets of the IPv4 address in network byte order.
 func IP4AddressToBytes(ip net.IP) [4]byte {
 	ip4 := ip.To4()
 	if ip4 == nil {
@@ -134,6 +189,13 @@ func IP4AddressToBytes(ip net.IP) [4]byte {
 	return [4]byte{ip4[0], ip4[1], ip4[2], ip4[3]}
 }
 
+// IP6AddressToBytes converts the given net.IPv6 address to a fixed-size byte array.
+// The resulting byte array contains the individual bytes of the IPv6 address in the same order as the original address.
+// Each byte of the byte array corresponds to a byte of the IPv6 address.
+// For example, the first byte of the byte array corresponds to the first byte of the IPv6 address, and so on.
+// The byte array has a length of 16 bytes.
+//
+// Note: This function assumes that the given net.IPv6 address is a valid IPv6 address.
 func IP6AddressToBytes(ip net.IP) [16]byte {
 	return [16]byte{
 		ip[0], ip[1], ip[2], ip[3],

inet_unix.go

@@ -200,7 +200,7 @@ func inetAddrToSockaddr(addr Addr) unix.Sockaddr {
 	}
 }
 
-func sockaddr(sa unix.Sockaddr) (ptr unsafe.Pointer, n int, err error) {
+func sockaddr(sa Sockaddr) (ptr unsafe.Pointer, n int, err error) {
 	switch sa.(type) {
 	case *unix.SockaddrInet4:
 		return inet4Sockaddr(sa.(*unix.SockaddrInet4))