Add documentation links to improve navigation

Add documentation links and references to some of the main parts of the API so
that relevant structs, enums and methods can be navigated to more quickly. This
reduces the need for the search bar and thus makes it easier to find related
content wherever it is mentioned.

quinn/src/builders.rs

@@ -11,9 +11,12 @@ use crate::{
 #[cfg(feature = "rustls")]
 use crate::{Certificate, CertificateChain, PrivateKey};
 
-/// A helper for constructing an `Endpoint`.
+/// A helper for constructing an [`Endpoint`].
 ///
-/// See `ClientConfigBuilder` for details on trust defaults.
+/// See [`ClientConfigBuilder`] for details on trust defaults.
+///
+/// [`Endpoint`]: crate::generic::Endpoint
+/// [`ClientConfigBuilder`]: crate::generic::ClientConfigBuilder
 #[derive(Clone, Debug)]
 pub struct EndpointBuilder<S>
 where
@@ -85,7 +88,9 @@ where
 
     /// Set the default configuration used for outgoing connections.
     ///
-    /// The default can be overriden by using `Endpoint::connect_with`.
+    /// The default can be overriden by using [`Endpoint::connect_with()`].
+    ///
+    /// [`Endpoint::connect_with()`]: crate::generic::Endpoint::connect_with
     pub fn default_client_config(&mut self, config: ClientConfig<S>) -> &mut Self {
         self.default_client_config = config;
         self
@@ -113,8 +118,11 @@ pub enum EndpointError {
     Socket(io::Error),
 }
 
-/// Helper for constructing a `ServerConfig` to be passed to `EndpointBuilder::listen` to enable
-/// incoming connections.
+/// Helper for constructing a [`ServerConfig`] to be passed to [`EndpointBuilder::listen()`] to
+/// enable incoming connections.
+///
+/// [`ServerConfig`]: crate::generic::ServerConfig
+/// [`EndpointBuilder::listen()`]: crate::generic::EndpointBuilder::listen
 pub struct ServerConfigBuilder<S>
 where
     S: proto::crypto::Session,
@@ -201,9 +209,11 @@ where
 
 /// Helper for creating new outgoing connections.
 ///
-/// If the `native-certs` and `ct-logs` features are enabled, `ClientConfigBuilder::default()` will
+/// If the `native-certs` and `ct-logs` features are enabled, [`ClientConfigBuilder::default()`] will
 /// construct a configuration that trusts the host OS certificate store and uses built-in
 /// certificate transparency logs respectively. These features are both enabled by default.
+///
+/// [`ClientConfigBuilder::default()`]: #method.default
 pub struct ClientConfigBuilder<S>
 where
     S: proto::crypto::Session,
@@ -218,19 +228,27 @@ where
     /// Construct a builder using `config` as the initial state.
     ///
     /// If you want to trust the usual certificate authorities trusted by the system, use
-    /// `ClientConfigBuilder::default()` with the `native-certs` and `ct-logs` features enabled
+    /// [`ClientConfigBuilder::default()`] with the `native-certs` and `ct-logs` features enabled
     /// instead.
     ///
     /// The `ClientConfigBuilder` provides a number of shortcuts to customize the TLS client
-    /// behavior. However, if you want to take full control over the client's behavior
-    /// (such as setting up TLS mutual authentication), you can use the associated `new()` function
-    /// to provide a `ClientConfig` with TLS configuration provided directly through its `crypto`
+    /// behavior. However, if you want to take full control over the client's behavior (such as
+    /// setting up TLS mutual authentication), you can use the associated [`new()`] function to
+    /// provide a [`ClientConfig`] with TLS configuration provided directly through its `crypto`
     /// field).
+    ///
+    /// [`ClientConfigBuilder::default()`]: #method.default
+    /// [`new()`]: ClientConfigBuilder::new
+    /// [`ClientConfig`]: crate::generic::ClientConfig
     pub fn new(config: ClientConfig<S>) -> Self {
         Self { config }
     }
 
-    /// Begin connecting from `endpoint` to `addr`.
+    /// Consume the builder and return the [`ClientConfig`], which can then be used to configure
+    /// outgoing connections from an [`Endpoint`].
+    ///
+    /// [`ClientConfig`]: crate::generic::ClientConfig
+    /// [`Endpoint`]: crate::generic::Endpoint
     pub fn build(self) -> ClientConfig<S> {
         self.config
     }
@@ -243,6 +261,8 @@ impl ClientConfigBuilder<proto::crypto::rustls::TlsSession> {
     /// For more advanced/less secure certificate verification, construct a [`ClientConfig`]
     /// manually and use rustls's `dangerous_configuration` feature to override the certificate
     /// verifier.
+    ///
+    /// [`ClientConfig`]: crate::generic::ClientConfig
     pub fn add_certificate_authority(
         &mut self,
         cert: Certificate,

quinn/src/connection.rs

@@ -197,7 +197,9 @@ let NewConnection { connection, .. } = { new_connection };
 ```"
 )]
 ///
-/// You can also explicitly invoke `Connection::close` at any time.
+/// You can also explicitly invoke [`Connection::close()`] at any time.
+///
+/// [`Connection::close()`]: crate::generic::Connection::close
 #[derive(Debug)]
 #[non_exhaustive]
 pub struct NewConnection<S>
@@ -209,8 +211,10 @@ where
     /// Unidirectional streams initiated by the peer, in the order they were opened
     ///
     /// Note that data for separate streams may be delivered in any order. In other words, reading
-    /// from streams in the order they're opened is not optimal. See `IncomingUniStreams` for
+    /// from streams in the order they're opened is not optimal. See [`IncomingUniStreams`] for
     /// details.
+    ///
+    /// [`IncomingUniStreams`]: crate::generic::IncomingUniStreams
     pub uni_streams: IncomingUniStreams<S>,
     /// Bidirectional streams initiated by the peer, in the order they were opened
     pub bi_streams: IncomingBiStreams<S>,
@@ -290,10 +294,13 @@ where
 ///
 /// If all references to a connection (including every clone of the `Connection` handle, streams of
 /// incoming streams, and the various stream types) other than the `ConnectionDriver` have been
-/// dropped, the the connection will be automatically closed with an `error_code` of 0 and an empty
-/// `reason`. You can also close the connection explicitly by calling `Connection::close()`.
+/// dropped, then the connection will be automatically closed with an `error_code` of 0 and an
+/// empty `reason`. You can also close the connection explicitly by calling
+/// [`Connection::close()`].
 ///
 /// May be cloned to obtain another handle to the same connection.
+///
+/// [`Connection::close()`]: Connection::close
 #[derive(Debug)]
 pub struct Connection<S: proto::crypto::Session>(ConnectionRef<S>);
 
@@ -327,15 +334,19 @@ where
 
     /// Close the connection immediately.
     ///
-    /// Pending operations will fail immediately with `ConnectionError::LocallyClosed`. Delivery of
-    /// data on unfinished streams is not guaranteed, so the application must call this only when
-    /// all important communications have been completed, e.g. by calling `finish` on outstanding
-    /// `SendStream`s and waiting for the resulting futures to complete.
+    /// Pending operations will fail immediately with [`ConnectionError::LocallyClosed`]. Delivery
+    /// of data on unfinished streams is not guaranteed, so the application must call this only
+    /// when all important communications have been completed, e.g. by calling [`finish`] on
+    /// outstanding [`SendStream`]s and waiting for the resulting futures to complete.
     ///
     /// `error_code` and `reason` are not interpreted, and are provided directly to the peer.
     ///
     /// `reason` will be truncated to fit in a single packet with overhead; to improve odds that it
     /// is preserved in full, it should be kept under 1KiB.
+    ///
+    /// [`ConnectionError::LocallyClosed`]: crate::ConnectionError::LocallyClosed
+    /// [`finish`]: crate::generic::SendStream::finish
+    /// [`SendStream`]: crate::generic::SendStream
     pub fn close(&self, error_code: VarInt, reason: &[u8]) {
         let conn = &mut *self.0.lock().unwrap();
         conn.close(error_code, Bytes::copy_from_slice(reason));
@@ -365,7 +376,7 @@ where
         }
     }
 
-    /// Compute the maximum size of datagrams that may passed to `send_datagram`
+    /// Compute the maximum size of datagrams that may be passed to [`send_datagram()`].
     ///
     /// Returns `None` if datagrams are unsupported by the peer or disabled locally.
     ///
@@ -374,6 +385,8 @@ where
     /// limit is large this is guaranteed to be a little over a kilobyte at minimum.
     ///
     /// Not necessarily the maximum size of received datagrams.
+    ///
+    /// [`send_datagram()`]: Connection::send_datagram
     pub fn max_datagram_size(&self) -> Option<usize> {
         self.0.lock().unwrap().inner.max_datagram_size()
     }
@@ -389,7 +402,9 @@ where
     /// Parameters negotiated during the handshake
     ///
     /// Guaranteed to return `Some` on fully established connections or after
-    /// `Connecting::handshake_data` succeeds.
+    /// [`Connecting::handshake_data()`] succeeds.
+    ///
+    /// [`Connection::handshake_data()`]: crate::generic::Connecting::handshake_data
     pub fn handshake_data(&self) -> Option<S::HandshakeData> {
         self.0
             .lock()

quinn/src/endpoint.rs

@@ -64,7 +64,9 @@ where
 
     /// Connect to a remote endpoint using a custom configuration.
     ///
-    /// See `connect` for details.
+    /// See [`connect()`] for details.
+    ///
+    /// [`connect()`]: Endpoint::connect
     pub fn connect_with(
         &self,
         config: ClientConfig<S>,
@@ -106,7 +108,9 @@ where
 
     /// Close all of this endpoint's connections immediately and cease accepting new connections.
     ///
-    /// See `Connection::close` for details.
+    /// See [`Connection::close()`] for details.
+    ///
+    /// [`Connection::close()`]: crate::generic::Connection::close
     pub fn close(&self, error_code: VarInt, reason: &[u8]) {
         let reason = Bytes::copy_from_slice(reason);
         let mut endpoint = self.inner.lock().unwrap();
@@ -130,8 +134,11 @@ where
     /// the idle timeout period.
     ///
     /// Does not proactively close existing connections or cause incoming connections to be
-    /// rejected. Consider calling `Endpoint::close` and dropping the `Incoming` stream if that is
-    /// desired.
+    /// rejected. Consider calling [`close()`] and dropping the [`Incoming`] stream if
+    /// that is desired.
+    ///
+    /// [`close()`]: Endpoint::close
+    /// [`Incoming`]: crate::generic::Incoming
     pub async fn wait_idle(&self) {
         let mut state = broadcast::State::default();
         futures::future::poll_fn(|cx| {

quinn/src/streams.rs

@@ -20,8 +20,10 @@ use crate::{connection::ConnectionRef, VarInt};
 
 /// A stream that can only be used to send data
 ///
-/// If dropped, streams that haven't been explicitly `reset` will continue to (re)transmit
+/// If dropped, streams that haven't been explicitly [`reset()`] will continue to (re)transmit
 /// previously written data until it has been fully acknowledged or the connection is closed.
+///
+/// [`reset()`]: SendStream::reset
 #[derive(Debug)]
 pub struct SendStream<S>
 where
@@ -282,8 +284,14 @@ where
 /// A stream that can only be used to receive data
 ///
 /// `stop(0)` is implicitly called on drop unless:
-/// - `ReadError::Finished` has been emitted, or
-/// - `stop` was called explicitly
+/// - A variant of [`ReadError`] has been emitted by [`read()`], [`read_exact()`] or [`read_unordered()`]
+/// - [`stop()`] was called explicitly
+///
+/// [`ReadError`]: crate::ReadError
+/// [`read()`]: RecvStream::read
+/// [`read_exact()`]: RecvStream::read_exact
+/// [`read_unordered()`]: RecvStream::read_unordered
+/// [`stop()`]: RecvStream::stop
 #[derive(Debug)]
 pub struct RecvStream<S>
 where
@@ -318,16 +326,20 @@ where
     /// improved performance.
     ///
     /// # Panics
-    /// - If used after `read_unordered` on the same stream.
+    /// - If used after [`read_unordered()`] on the same stream.
     ///   This is forbidden because an unordered read could consume a segment of data from a
     ///   location other than the start of the receive buffer, making it impossible for future
+    ///
+    /// [`read_unordered()`]: RecvStream::read_unordered
     pub fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, S> {
         Read { stream: self, buf }
     }
 
     /// Read an exact number of bytes contiguously from the stream.
     ///
-    /// See `read` for details.
+    /// See [`read()`] for details.
+    ///
+    /// [`read()`]: RecvStream::read
     pub fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, S> {
         ReadExact {
             stream: self,
@@ -422,12 +434,14 @@ where
 
     /// Convenience method to read all remaining data into a buffer
     ///
-    /// The returned future fails with `ReadToEnd::TooLong` if it's longer than `size_limit`
-    /// bytes. Uses unordered reads to be more efficient than using `AsyncRead` would
-    /// allow. `size_limit` should be set to limit worst-case memory use.
+    /// The returned future fails with [`ReadToEndError::TooLong`] if it's longer than `size_limit`
+    /// bytes. Uses unordered reads to be more efficient than using `AsyncRead` would allow.
+    /// `size_limit` should be set to limit worst-case memory use.
     ///
     /// If unordered reads have already been made, the resulting buffer may have gaps containing
     /// arbitrary data.
+    ///
+    /// [`ReadToEndError::TooLong`]: crate::ReadToEndError::TooLong
     pub fn read_to_end(self, size_limit: usize) -> ReadToEnd<S> {
         ReadToEnd {
             stream: self,
@@ -467,7 +481,9 @@ where
     }
 }
 
-/// Future produced by `read_to_end`
+/// Future produced by [`RecvStream::read_to_end()`].
+///
+/// [`RecvStream::read_to_end()`]: crate::generic::RecvStream::read_to_end
 pub struct ReadToEnd<S>
 where
     S: proto::crypto::Session,
@@ -514,7 +530,9 @@ where
     }
 }
 
-/// Error from the ReadToEnd future
+/// Error from the [`ReadToEnd`] future.
+///
+/// [`ReadToEnd`]: crate::generic::ReadToEnd
 #[derive(Debug, Error, Clone, PartialEq, Eq)]
 pub enum ReadToEndError {
     /// An error occurred during reading
@@ -605,7 +623,10 @@ pub enum ReadError {
     IllegalOrderedRead,
     /// This was a 0-RTT stream and the server rejected it.
     ///
-    /// Can only occur on clients for 0-RTT streams (opened using `Connecting::into_0rtt()`).
+    /// Can only occur on clients for 0-RTT streams, which can be opened using
+    /// [`Connecting::into_0rtt()`].
+    ///
+    /// [`Connecting::into_0rtt()`]: crate::generic::Connecting::into_0rtt()
     #[error(display = "0-RTT rejected")]
     ZeroRttRejected,
 }
@@ -641,7 +662,10 @@ pub enum WriteError {
     UnknownStream,
     /// This was a 0-RTT stream and the server rejected it.
     ///
-    /// Can only occur on clients for 0-RTT streams (opened using `Connecting::into_0rtt()`).
+    /// Can only occur on clients for 0-RTT streams, which can be opened using
+    /// [`Connecting::into_0rtt()`].
+    ///
+    /// [`Connecting::into_0rtt()`]: crate::generic::Connecting::into_0rtt()
     #[error(display = "0-RTT rejected")]
     ZeroRttRejected,
 }
@@ -657,7 +681,10 @@ pub enum StoppedError {
     UnknownStream,
     /// This was a 0-RTT stream and the server rejected it.
     ///
-    /// Can only occur on clients for 0-RTT streams (opened using `Connecting::into_0rtt()`).
+    /// Can only occur on clients for 0-RTT streams, which can be opened using
+    /// [`Connecting::into_0rtt()`].
+    ///
+    /// [`Connecting::into_0rtt()`]: crate::generic::Connecting::into_0rtt()
     #[error(display = "0-RTT rejected")]
     ZeroRttRejected,
 }
@@ -676,7 +703,9 @@ impl From<WriteError> for io::Error {
     }
 }
 
-/// Future produced by `RecvStream::read`
+/// Future produced by [`RecvStream::read()`].
+///
+/// [`RecvStream::read()`]: crate::generic::RecvStream::read
 pub struct Read<'a, S>
 where
     S: proto::crypto::Session,
@@ -696,7 +725,9 @@ where
     }
 }
 
-/// Future produced by `RecvStream::read_exact`
+/// Future produced by [`RecvStream::read_exact()`].
+///
+/// [`RecvStream::read_exact()`]: crate::generic::RecvStream::read_exact
 pub struct ReadExact<'a, S>
 where
     S: proto::crypto::Session,
@@ -736,7 +767,9 @@ pub enum ReadExactError {
     ReadError(ReadError),
 }
 
-/// Future produced by `RecvStream::read_unordered`
+/// Future produced by [`RecvStream::read_unordered()`].
+///
+/// [`RecvStream::read_unordered()`]: crate::generic::RecvStream::read_unordered
 pub struct ReadUnordered<'a, S>
 where
     S: proto::crypto::Session,
@@ -754,7 +787,9 @@ where
     }
 }
 
-/// Future produced by `SendStream::write`
+/// Future produced by [`SendStream::write()`].
+///
+/// [`SendStream::write()`]: crate::generic::SendStream::write
 pub struct Write<'a, S>
 where
     S: proto::crypto::Session,
@@ -774,7 +809,9 @@ where
     }
 }
 
-/// Future produced by `SendStream::write_all`
+/// Future produced by [`SendStream::write_all()`].
+///
+/// [`SendStream::write_all()`]: crate::generic::SendStream::write_all
 pub struct WriteAll<'a, S>
 where
     S: proto::crypto::Session,