improve the description of how we handle net.PacketConns

client.go

@@ -59,6 +59,7 @@ var (
 )
 
 // DialAddr establishes a new QUIC connection to a server.
+// It uses a new UDP connection and closes this connection when the QUIC session is closed.
 // The hostname for SNI is taken from the given address.
 func DialAddr(
 	addr string,
@@ -69,7 +70,7 @@ func DialAddr(
 }
 
 // DialAddrContext establishes a new QUIC connection to a server using the provided context.
-// The hostname for SNI is taken from the given address.
+// See DialAddr for details.
 func DialAddrContext(
 	ctx context.Context,
 	addr string,
@@ -88,6 +89,8 @@ func DialAddrContext(
 }
 
 // Dial establishes a new QUIC connection to a server using a net.PacketConn.
+// The same PacketConn can be used for multiple calls to Dial and Listen,
+// QUIC connection IDs are used for demultiplexing the different connections.
 // The host parameter is used for SNI.
 func Dial(
 	pconn net.PacketConn,
@@ -100,7 +103,7 @@ func Dial(
 }
 
 // DialContext establishes a new QUIC connection to a server using a net.PacketConn using the provided context.
-// The host parameter is used for SNI.
+// See Dial for details.
 func DialContext(
 	ctx context.Context,
 	pconn net.PacketConn,

server.go

@@ -98,7 +98,8 @@ var _ Listener = &server{}
 var _ unknownPacketHandler = &server{}
 
 // ListenAddr creates a QUIC server listening on a given address.
-// The tls.Config must not be nil, the quic.Config may be nil.
+// The tls.Config must not be nil and must contain a certificate configuration.
+// The quic.Config may be nil, in that case the default values will be used.
 func ListenAddr(addr string, tlsConf *tls.Config, config *Config) (Listener, error) {
 	udpAddr, err := net.ResolveUDPAddr("udp", addr)
 	if err != nil {
@@ -117,7 +118,11 @@ func ListenAddr(addr string, tlsConf *tls.Config, config *Config) (Listener, err
 }
 
 // Listen listens for QUIC connections on a given net.PacketConn.
-// The tls.Config must not be nil, the quic.Config may be nil.
+// A single PacketConn only be used for a single call to Listen.
+// The PacketConn can be used for simultaneous calls to Dial.
+// QUIC connection IDs are used for demultiplexing the different connections.
+// The tls.Config must not be nil and must contain a certificate configuration.
+// The quic.Config may be nil, in that case the default values will be used.
 func Listen(conn net.PacketConn, tlsConf *tls.Config, config *Config) (Listener, error) {
 	return listen(conn, tlsConf, config)
 }