Change https://golang.org/cl/132437 mentions this issue: net: extend documentation for net.FileConn()

For what kind of code does this matter?

This is particularly with unix sockets where one might want access to the non-generic Conn methods. (e.g. (*UnixConn).SetWriteBuffer()1 which isn't in the Conn interface)

My specific use-case is that I'm constructing a unix socket with syscall.SocketPair()2 to communicate data with a subprocess that's being spawned with os.Exec, and it's much nicer if my function for creating the socket can return the correct net.Conn implementation.

In this case, I'd like the documentation reflect that this will never return the "failed to type-assert back to a UnixConn" error below (with some error-checking elided for simplicity):

func SocketPair() (*os.File, *net.UnixConn, error)
	fds, _ := syscall.Socketpair(syscall.AF_UNIX, syscall.SOCK_STREAM, 0)

	// Convert these into os.files.
	var files [2]*os.File
	for i, fd := range fds {
		files[i] = os.NewFile(uintptr(fd), fmt.Sprintf("anonymous-socket-%d", i))
	}

	conn, _ := net.FileConn(files[1])

	unixConn, ok := conn.(*net.UnixConn)
	if !ok {
		for _, file := range files {
			file.Close()
		}
		return nil, nil, fmt.Errorf("failed to type-assert back to a UnixConn. conn type: %T", conn)
	}

	// Since FileConn dup'd the files[1] FD, we need to close that FD.
	// Since we never wrote to this FD closing should always succeed.
	if err := files[1].Close(); err != nil {
		// We don't want to leak an FD for every process.
		log.Panicf("Failed to close a unix FD: %s", err)
	}
	return files[0], unixConn, nil

The use-case for Dial() is less clear to me due to the presence of DialUnix(), DialTCP, etc, but it seems odd to document that the less-used FileConn won't use a random private type when Dial() doesn't document similar behavior.