/cc @mikioh

in it's current form are at best useless

I'm relieved to see the word "useless" instead of "considered harmful" because the package net is a sort of intersection between various operating system kernels, various network- and transport-layer protocols. The API surfaces and docs are able to propagate wrong information easily, to mislead API users into doing wrong things. I agree that the documentation update is necessary; see also #29978.

Requests for more better API surfaces should be addressed in #28900. The current API surfaces have a history, for example, @rsc vs. @mikioh :), wandering ipv4 and ipv6 packages and settlement of the x/net repository. #28900 is a new hope.

I think the documentation for ReadMsgUDP() is OK, and definitely not useless. I see no solution to that use of low-level, platform dependent networking features requires knowing about the network stack (how do you get the incoming interface for a UDP datagram on Windows?!). But x/net/ipv4 could definitely have improved documentation and a complete example on enabling, receiving and parsing the oob data.

For func (c *PacketConn) SetControlMessage(cf ControlFlags, on bool) error, the on flag is nowhere documented. It seems that true means to set the flags and false means to clear the provided flags. And, it is not supported on Windows.

@antong As both a library developer and library user, there is a reason why I hold that the documentation is not ok and is in fact useless. If we look at the actual purpose of a library, we find that it exists to provide an abstraction of commonly repeated behaviors and simplify the job of the developer using the library. Examining the net package, the majority of the API revolves around interacting with network protocols and paradigms; not the underlying OS level API.

The net library exists for the explicit purpose of allowing a developer to work with network communications without understanding the intimate details of the network API of every platform. I understand now (after digging through the entirety of the net and x/net/ipv4 source) that the ReadMsgXXX methods are nothing more than a mapping layer on top of 'recvmsg', but there is no way to make that leap with only the documentation.

If ReadMsgXXX is a method that cannot be used without understanding the underlying network stack, fine! Tell me that in the documentation! Tell me what I will need to know to understand what to do! There are references to various RFCs scattered throughout the docs(!), but when we get to a function which is essentially a direct mapping onto the OS syscall, there's nothing; no mention of that, no direct pointer of what to look for in other documentation, no "Here be dragons", just some vague mention of "these other packages can be used to manipulate what is returned in oob".

@mikioh The API split between net and x/net makes a fair bit of sense, but I'll admit to not understanding the reasoning for placing SetControlMessage in x/net and not duplicated in net as well (a la ReadMsgXXX); I'm guessing there was a bit of a contentious debate on the subject.