From 65c33b3cd16d1d6efb8dda16e40d50034dd5137e Mon Sep 17 00:00:00 2001 From: GunnarMorrigan <13799935+GunnarMorrigan@users.noreply.github.com> Date: Tue, 16 Jan 2024 19:57:50 +0100 Subject: [PATCH] Fix documentation links --- src/client.rs | 16 ++++++++++++++++ src/error.rs | 4 ++-- src/lib.rs | 11 +++++------ src/smol/network.rs | 11 +++++------ src/tokio/network.rs | 4 +--- 5 files changed, 29 insertions(+), 17 deletions(-) diff --git a/src/client.rs b/src/client.rs index 1ee760c..a58938f 100644 --- a/src/client.rs +++ b/src/client.rs @@ -47,6 +47,22 @@ impl MqttClient { /// This function is only here for you to use during testing of for example your handler /// For control over the input of this type look at [`MqttClient::test_custom_client`] + /// + /// The returned values should not be dropped otherwise the client won't be able to operate normally. + /// + /// # Example + /// ``` + /// let ( + /// client, // An instance of this client + /// ids, // Allows you to indicate which packet IDs have become available again. + /// network_receiver // Messages send through the `client` will be dispatched through this channel + /// ) = MqttClient::test_client(); + /// + /// // perform testing + /// + /// // Make sure to not drop these before the test is done! + /// std::hint::black_box((ids, network_receiver)); + /// ``` #[cfg(feature = "test")] pub fn test_client() -> (Self, crate::available_packet_ids::AvailablePacketIds, Receiver) { use async_channel::unbounded; diff --git a/src/error.rs b/src/error.rs index 602e923..ad1185d 100644 --- a/src/error.rs +++ b/src/error.rs @@ -43,7 +43,7 @@ pub enum ConnectionError { JoinError(#[from] tokio::task::JoinError), } -/// Errors that the [`mqrstt::MqttHandler`] can emit +/// Errors that the [`crate::MqttClient`] can emit #[derive(Debug, Clone, thiserror::Error)] pub enum HandlerError { #[error("Missing Packet ID")] @@ -71,7 +71,7 @@ pub enum HandlerError { UnexpectedPacket(PacketType), } -/// Errors producable by the [`mqrstt::AsyncClient`] +/// Errors producable by the [`crate::MqttClient`] #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] pub enum ClientError { #[error("Internal network channel is closed")] diff --git a/src/lib.rs b/src/lib.rs index 6951cfa..726f3cd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,14 +1,13 @@ //! A pure rust MQTT client which is easy to use, efficient and provides both sync and async options. //! //! Because this crate aims to be runtime agnostic the user is required to provide their own data stream. -//! For an async approach the stream has to implement the smol or tokio [`AsyncReadExt`] and [`AsyncWriteExt`] traits. -//! For a sync approach the stream has to implement the [`std::io::Read`] and [`std::io::Write`] traits. +//! For an async approach the stream has to implement the `AsyncReadExt` and `AsyncWriteExt` traits. +//! That is [`::tokio::io::AsyncReadExt`] and [`::tokio::io::AsyncWriteExt`] for tokio and [`::smol::io::AsyncReadExt`] and [`::smol::io::AsyncWriteExt`] for smol. //! //! Features: //! ---------------------------- //! - MQTT v5 //! - Runtime agnostic (Smol, Tokio) -//! - Sync //! - TLS/TCP //! - Lean //! - Keep alive depends on actual communication @@ -241,7 +240,7 @@ where H: AsyncEventHandlerMut, S: ::tokio::io::AsyncReadExt + ::tokio::io::AsyncWriteExt + Sized + Unpin, { - /// Creates the needed components to run the MQTT client using a stream that implements [`tokio::io::AsyncReadExt`] and [`tokio::io::AsyncWriteExt`] + /// Creates the needed components to run the MQTT client using a stream that implements [`::tokio::io::AsyncReadExt`] and [`::tokio::io::AsyncWriteExt`] /// This network is supposed to be ran on a single task/thread. The read and write operations happen one after the other. /// This approach does not give the most speed in terms of reading and writing but provides a simple and easy to use client with low overhead for low throughput clients. /// @@ -278,7 +277,7 @@ where H: AsyncEventHandler, S: ::tokio::io::AsyncReadExt + ::tokio::io::AsyncWriteExt + Sized + Unpin, { - /// Creates the needed components to run the MQTT client using a stream that implements [`tokio::io::AsyncReadExt`] and [`tokio::io::AsyncWriteExt`] + /// Creates the needed components to run the MQTT client using a stream that implements [`::tokio::io::AsyncReadExt`] and [`::tokio::io::AsyncWriteExt`] /// # Example /// /// ``` @@ -310,7 +309,7 @@ where H: AsyncEventHandlerMut, S: ::smol::io::AsyncReadExt + ::smol::io::AsyncWriteExt + Sized + Unpin, { - /// Creates the needed components to run the MQTT client using a stream that implements [`smol::io::AsyncReadExt`] and [`smol::io::AsyncWriteExt`] + /// Creates the needed components to run the MQTT client using a stream that implements [`::tokio::io::AsyncReadExt`] and [`::tokio::io::AsyncWriteExt`] /// ``` /// let (mut network, client) = mqrstt::NetworkBuilder::<(), smol::net::TcpStream> /// ::new_from_client_id("ExampleClient") diff --git a/src/smol/network.rs b/src/smol/network.rs index 5bd8ab6..66d641d 100644 --- a/src/smol/network.rs +++ b/src/smol/network.rs @@ -16,7 +16,7 @@ use crate::{AsyncEventHandlerMut, StateHandler}; use super::stream::Stream; -/// [`Network`] reads and writes to the network based on tokios [`AsyncReadExt`] [`AsyncWriteExt`]. +/// [`Network`] reads and writes to the network based on tokios [`::smol::io::AsyncReadExt`] [`::smol::io::AsyncWriteExt`]. /// This way you can provide the `connect` function with a TLS and TCP stream of your choosing. /// The most import thing to remember is that you have to provide a new stream after the previous has failed. /// (i.e. you need to reconnect after any expected or unexpected disconnect). @@ -89,13 +89,12 @@ where Ok(()) } - /// A single call to run will perform one of three tasks: - /// - Read from the stream and parse the bytes to packets for the user to handle - /// - Write user packets to stream - /// - Perform keepalive if necessary + /// A single call to [`Network::run`] will continiously perform the tasks mentioned below until an error is encountered. + /// 1. Read from the stream and parse the bytes to packets for the user to handle + /// 2. Write user packets to stream + /// 3. Perform keepalive if necessary /// /// This function can produce an indication of the state of the network or an error. - /// When the network is still active (i.e. stream is not closed and no disconnect packet has been processed) the network will return [`NetworkStatus::Active`] /// /// In all other cases the network is unusable anymore. /// The stream will be dropped and the internal buffers will be cleared. diff --git a/src/tokio/network.rs b/src/tokio/network.rs index 5f25047..d19b84b 100644 --- a/src/tokio/network.rs +++ b/src/tokio/network.rs @@ -19,9 +19,7 @@ use crate::{AsyncEventHandlerMut, StateHandler, NetworkStatus}; use super::{SequentialHandler, HandlerExt}; use super::stream::Stream; -// type StreamType = tokio::io::AsyncReadExt + tokio::io::AsyncWriteExt + Sized + Unpin + Send + 'static; - -/// [`Network`] reads and writes to the network based on tokios [`AsyncReadExt`] [`AsyncWriteExt`]. +/// [`Network`] reads and writes to the network based on tokios [`::tokio::io::AsyncReadExt`] [`::tokio::io::AsyncWriteExt`]. /// This way you can provide the `connect` function with a TLS and TCP stream of your choosing. /// The most import thing to remember is that you have to provide a new stream after the previous has failed. /// (i.e. you need to reconnect after any expected or unexpected disconnect).