From 68d019c5dca69afeafa842ca17ad2a24bbea4a22 Mon Sep 17 00:00:00 2001 From: hayabusa-cloud Date: Sun, 16 Jun 2024 20:37:19 +0900 Subject: [PATCH] docs: add code comments --- inet.go | 70 +++++++++++++++++++++++++++++++++++++++++++++++++--- inet_unix.go | 2 +- 2 files changed, 67 insertions(+), 5 deletions(-) diff --git a/inet.go b/inet.go index 079daaa..b79864f 100644 --- a/inet.go +++ b/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 "" 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 "" @@ -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], diff --git a/inet_unix.go b/inet_unix.go index c4a53ab..392112c 100644 --- a/inet_unix.go +++ b/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))