add some docs to netdev interface

netdev.go

@@ -55,14 +55,86 @@ type netdever interface {
 	// DHCP or statically
 	Addr() (netip.Addr, error)
 
-	// Berkely Sockets-like interface, Go-ified.  See man page for socket(2), etc.
+	// # Socket Address family/domain argument
-	Socket(domain int, stype int, protocol int) (int, error)
+	//
+	// Socket address families specifies a communication domain:
+	//  - AF_UNIX, AF_LOCAL(synonyms): Local communication For further information, see unix(7).
+	//  - AF_INET: IPv4 Internet protocols.  For further information, see ip(7).
+	//
+	// # Socket type argument
+	//
+	// Socket types which specifies the communication semantics.
+	//  - SOCK_STREAM: Provides sequenced, reliable, two-way, connection-based
+	//  byte streams.  An out-of-band data transmission mechanism may be supported.
+	//  - SOCK_DGRAM: Supports datagrams (connectionless, unreliable messages of
+	//  a fixed maximum length).
+	//
+	// The type argument serves a second purpose: in addition to specifying a
+	// socket type, it may include the bitwise OR of any of the following values,
+	// to modify the behavior of socket():
+	//  - SOCK_NONBLOCK: Set the O_NONBLOCK file status flag on the open file description.
+	//
+	// # Socket protocol argument
+	//
+	// The protocol specifies a particular protocol to be used with the
+	// socket.  Normally only a single protocol exists to support a
+	// particular socket type within a given protocol family, in which
+	// case protocol can be specified as 0. However, it is possible
+	// that many protocols may exist, in which case a particular
+	// protocol must be specified in this manner.
+	//
+	// # Return value
+	//
+	// On success, a file descriptor for the new socket is returned. Quoting man pages:
+	// "On error, -1 is returned, and errno is set to indicate the error." Since
+	// this is not C we may use a error type native to Go to represent the error
+	// ocurred which by itself not only notifies of an error but also provides
+	// information on the error as a human readable string when calling the Error method.
+	Socket(domain int, stype int, protocol int) (sockfd int, _ error)
 	Bind(sockfd int, ip netip.AddrPort) error
 	Connect(sockfd int, host string, ip netip.AddrPort) error
 	Listen(sockfd int, backlog int) error
 	Accept(sockfd int, ip netip.AddrPort) (int, error)
+
+	// # Flags argument on Send and Recv
+	//
+	// The flags argument is formed by ORing one or more of the following values:
+	//  - MSG_CMSG_CLOEXEC: Set the close-on-exec flag for the file descriptor. Unix.
+	//  - MSG_DONTWAIT: Enables nonblocking operation. If call would block then returns error.
+	//  - MSG_ERRQUEUE: (see manpage) his flag specifies that queued errors should be received
+	//  from the socket error queue.
+	//  - MSG_OOB: his flag requests receipt of out-of-band data that would not be received in the normal data stream.
+	//  - MSG_PEEK: This flag causes the receive operation to return data from
+	//  the beginning of the receive queue without removing that data from the queue.
+	//  - MSG_TRUNC: Ask for real length of datagram even when it was longer than passed buffer.
+	//  - MSG_WAITALL: This flag requests that the operation block until the full request is satisfied.
+
 	Send(sockfd int, buf []byte, flags int, deadline time.Time) (int, error)
 	Recv(sockfd int, buf []byte, flags int, deadline time.Time) (int, error)
 	Close(sockfd int) error
+
+	// SetSockOpt manipulates options for the socket
+	// referred to by the file descriptor sockfd.  Options may exist at
+	// multiple protocol levels; they are always present at the
+	// uppermost socket level.
+	//
+	// # Level argument
+	//
+	// When manipulating socket options, the level at which the option
+	// resides and the name of the option must be specified.  To
+	// manipulate options at the sockets API level, level is specified
+	// as SOL_SOCKET.  To manipulate options at any other level the
+	// protocol number of the appropriate protocol controlling the
+	// option is supplied.  For example, to indicate that an option is
+	// to be interpreted by the TCP protocol, level should be set to the
+	// protocol number of TCP; see getprotoent(3).
+	//
+	// # Option argument
+	//
+	// The arguments optval and optlen are used to access option values
+	// for setsockopt().  For getsockopt() they identify a buffer in
+	// which the value for the requested option(s) are to be returned.
+	// In Go we provide developers with an `any` interface to be able
+	// to pass driver-specific configurations.
 	SetSockOpt(sockfd int, level int, opt int, value interface{}) error
 }