diff --git a/quinn/src/builders.rs b/quinn/src/builders.rs index f58c42262..aa663bfe3 100644 --- a/quinn/src/builders.rs +++ b/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 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) -> &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 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 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) -> 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 { self.config } @@ -243,6 +261,8 @@ impl ClientConfigBuilder { /// 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, diff --git a/quinn/src/connection.rs b/quinn/src/connection.rs index 3dc22a4d1..8d10c1fbf 100644 --- a/quinn/src/connection.rs +++ b/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 @@ -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, /// Bidirectional streams initiated by the peer, in the order they were opened pub bi_streams: IncomingBiStreams, @@ -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(ConnectionRef); @@ -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 { 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 { self.0 .lock() diff --git a/quinn/src/endpoint.rs b/quinn/src/endpoint.rs index 046084494..cf269d8ee 100644 --- a/quinn/src/endpoint.rs +++ b/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, @@ -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| { diff --git a/quinn/src/streams.rs b/quinn/src/streams.rs index a873acc99..c2d6204cb 100644 --- a/quinn/src/streams.rs +++ b/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 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 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 { 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 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 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,