From ee2575794e91b9457a74a95daf1dcc707058cd58 Mon Sep 17 00:00:00 2001 From: mat Date: Sun, 12 Oct 2025 23:01:54 +0300 Subject: upgrade deps and clean up lots of doc comments --- azalea-protocol/src/common/client_information.rs | 15 ++-- azalea-protocol/src/connect.rs | 84 +++++++++++++--------- azalea-protocol/src/lib.rs | 18 +++-- azalea-protocol/src/packets/game/c_add_entity.rs | 5 +- .../src/packets/game/c_map_item_data.rs | 2 +- azalea-protocol/src/packets/game/c_player_chat.rs | 9 +-- azalea-protocol/src/packets/game/s_use_item_on.rs | 7 +- azalea-protocol/src/packets/mod.rs | 2 +- azalea-protocol/src/read.rs | 8 ++- 9 files changed, 91 insertions(+), 59 deletions(-) (limited to 'azalea-protocol/src') diff --git a/azalea-protocol/src/common/client_information.rs b/azalea-protocol/src/common/client_information.rs index 690d052a..5dedd1a8 100644 --- a/azalea-protocol/src/common/client_information.rs +++ b/azalea-protocol/src/common/client_information.rs @@ -5,8 +5,9 @@ use azalea_core::bitset::FixedBitSet; use bevy_ecs::component::Component; /// A component that contains some of the "settings" for this client that are -/// sent to the server, such as render distance. This is only present on local -/// players. +/// sent to the server, such as render distance. +/// +/// This is only present on local players. #[derive(Clone, Debug, AzBuf, PartialEq, Eq, Component)] pub struct ClientInformation { /// The locale of the client. @@ -14,11 +15,13 @@ pub struct ClientInformation { /// The view distance of the client in chunks, same as the render distance /// in-game. pub view_distance: u8, - /// The types of chat messages the client wants to receive. Note that many - /// servers ignore this. + /// The types of chat messages the client wants to receive. + /// + /// Note that this is enforced by the server, and many servers ignore this. pub chat_visibility: ChatVisibility, - /// Whether the messages sent from the server should have colors. Note that - /// many servers ignore this and always send colored messages. + /// Whether the messages sent from the server should have colors. + /// + /// Note that many servers ignore this and always send colored messages. pub chat_colors: bool, pub model_customization: ModelCustomization, pub main_hand: HumanoidArm, diff --git a/azalea-protocol/src/connect.rs b/azalea-protocol/src/connect.rs index 78ad6d81..febb2337 100644 --- a/azalea-protocol/src/connect.rs +++ b/azalea-protocol/src/connect.rs @@ -247,7 +247,9 @@ where self.writer.write(packet).await } - /// Split the reader and writer into two objects. This doesn't allocate. + /// Split the reader and writer into two objects. + /// + /// This doesn't allocate. #[must_use] pub fn into_split(self) -> (ReadConnection, WriteConnection) { (self.reader, self.writer) @@ -304,8 +306,9 @@ impl Connection { Self::new_from_stream(stream).await } - /// Create a new connection to the given address and Socks5 proxy. If you're - /// not using a proxy, use [`Self::new`] instead. + /// Create a new connection to the given address and Socks5 proxy. + /// + /// If you're not using a proxy, use [`Self::new`] instead. pub async fn new_with_proxy( address: &SocketAddr, proxy: Proxy, @@ -320,8 +323,10 @@ impl Connection { Self::new_from_stream(stream.into_inner()).await } - /// Create a new connection from an existing stream. Useful if you want to - /// set custom options on the stream. Otherwise, just use [`Self::new`]. + /// Create a new connection from an existing stream. + /// + /// Useful if you want to set custom options on the stream. Otherwise, just + /// use [`Self::new`]. pub async fn new_from_stream(stream: TcpStream) -> Result { let (read_stream, write_stream) = stream.into_split(); @@ -346,15 +351,17 @@ impl Connection { }) } - /// Change our state from handshake to login. This is the state that is used - /// for logging in. + /// Change our state from handshake to login. + /// + /// This is the state that is used for logging in. #[must_use] pub fn login(self) -> Connection { Connection::from(self) } - /// Change our state from handshake to status. This is the state that is - /// used for pinging the server. + /// Change our state from handshake to status. + /// + /// This is the state that is used for pinging the server. #[must_use] pub fn status(self) -> Connection { Connection::from(self) @@ -363,9 +370,10 @@ impl Connection { impl Connection { /// Set our compression threshold, i.e. the maximum size that a packet is - /// allowed to be without getting compressed. Setting it to 0 means every - /// packet will be compressed. If you set it to less than 0, - /// then compression is disabled. + /// allowed to be without getting compressed. + /// + /// Setting it to 0 means every packet will be compressed. If you set it to + /// less than 0 then compression is disabled. pub fn set_compression_threshold(&mut self, threshold: i32) { // if you pass a threshold of less than 0, compression is disabled if threshold >= 0 { @@ -377,24 +385,28 @@ impl Connection { } } - /// Set the encryption key that is used to encrypt and decrypt packets. It's - /// the same for both reading and writing. + /// Set the encryption key that is used to encrypt and decrypt packets. + /// + /// It's the same for both reading and writing. pub fn set_encryption_key(&mut self, key: [u8; 16]) { let (enc_cipher, dec_cipher) = azalea_crypto::create_cipher(&key); self.reader.raw.dec_cipher = Some(dec_cipher); self.writer.raw.enc_cipher = Some(enc_cipher); } - /// Change our state from login to configuration. This is the state where - /// the server sends us the registries and resource pack and stuff. + /// Change our state from login to configuration. + /// + /// This is the state where the server sends us the registries and the + /// resource pack. #[must_use] pub fn config(self) -> Connection { Connection::from(self) } /// Authenticate with Minecraft's servers, which is required to join - /// online-mode servers. This must happen when you get a - /// `ClientboundLoginPacket::Hello` packet. + /// online-mode servers. + /// + /// This must happen when you get a `ClientboundLoginPacket::Hello` packet. /// /// # Examples /// @@ -460,15 +472,18 @@ impl Connection { } impl Connection { - /// Change our state from handshake to login. This is the state that is used - /// for logging in. + /// Change our state from handshake to login. + /// + /// This is the state that is used while negotiating encryption and + /// authenticating with Mojang. #[must_use] pub fn login(self) -> Connection { Connection::from(self) } - /// Change our state from handshake to status. This is the state that is - /// used for pinging the server. + /// Change our state from handshake to status. + /// + /// This is the state that is used for pinging the server. #[must_use] pub fn status(self) -> Connection { Connection::from(self) @@ -477,8 +492,9 @@ impl Connection { impl Connection { /// Set our compression threshold, i.e. the maximum size that a packet is - /// allowed to be without getting compressed. If you set it to less than 0 - /// then compression gets disabled. + /// allowed to be without getting compressed. + /// + /// If you set it to less than 0 then compression gets disabled. pub fn set_compression_threshold(&mut self, threshold: i32) { // if you pass a threshold of less than 0, compression is disabled if threshold >= 0 { @@ -490,16 +506,18 @@ impl Connection { } } - /// Set the encryption key that is used to encrypt and decrypt packets. It's - /// the same for both reading and writing. + /// Set the encryption key that is used to encrypt and decrypt packets. + /// + /// It's the same for both reading and writing. pub fn set_encryption_key(&mut self, key: [u8; 16]) { let (enc_cipher, dec_cipher) = azalea_crypto::create_cipher(&key); self.reader.raw.dec_cipher = Some(dec_cipher); self.writer.raw.enc_cipher = Some(enc_cipher); } - /// Change our state from login to game. This is the state that's used when - /// the client is actually in the game. + /// Change our state from login to game. + /// + /// This is the state that's used when the client is actually in the game. #[must_use] pub fn game(self) -> Connection { Connection::from(self) @@ -526,8 +544,9 @@ impl Connection { } impl Connection { - /// Change our state from configuration to game. This is the state that's - /// used when the client is actually in the world. + /// Change our state from configuration to game. + /// + /// This is the state that's used when the client is actually in the world. #[must_use] pub fn game(self) -> Connection { Connection::from(self) @@ -535,8 +554,9 @@ impl Connection { } impl Connection { - /// Change our state from configuration to game. This is the state that's - /// used when the client is actually in the world. + /// Change our state from configuration to game. + /// + /// This is the state that's used when the client is actually in the world. #[must_use] pub fn game(self) -> Connection { Connection::from(self) diff --git a/azalea-protocol/src/lib.rs b/azalea-protocol/src/lib.rs index fd092293..fdba34bc 100644 --- a/azalea-protocol/src/lib.rs +++ b/azalea-protocol/src/lib.rs @@ -71,9 +71,11 @@ impl TryFrom for ServerAddress { } impl From for ServerAddress { - /// Convert an existing `SocketAddr` into a `ServerAddress`. This just - /// converts the ip to a string and passes along the port. The resolver - /// will realize it's already an IP address and not do any DNS requests. + /// Convert an existing `SocketAddr` into a `ServerAddress`. + /// + /// This just converts the IP to a string and passes along the port. The + /// resolver will realize it's already an IP address and not do any DNS + /// requests. fn from(addr: SocketAddr) -> Self { ServerAddress { host: addr.ip().to_string(), @@ -88,8 +90,9 @@ impl Display for ServerAddress { } } -/// Serde deserialization for ServerAddress. This is useful for config file -/// usage. +/// Serde deserialization for ServerAddress. +/// +/// This is useful if you're storing the server address in a config file. impl<'de> serde::Deserialize<'de> for ServerAddress { fn deserialize(deserializer: D) -> Result where @@ -100,8 +103,9 @@ impl<'de> serde::Deserialize<'de> for ServerAddress { } } -/// Serde serialization for ServerAddress. This uses the Display impl, so it -/// will serialize to a string. +/// Serde serialization for ServerAddress. +/// +/// This uses the Display impl, so it will serialize to a string. impl serde::Serialize for ServerAddress { fn serialize(&self, serializer: S) -> Result where diff --git a/azalea-protocol/src/packets/game/c_add_entity.rs b/azalea-protocol/src/packets/game/c_add_entity.rs index 7fb680a1..fe473289 100644 --- a/azalea-protocol/src/packets/game/c_add_entity.rs +++ b/azalea-protocol/src/packets/game/c_add_entity.rs @@ -30,8 +30,9 @@ pub struct ClientboundAddEntity { } impl ClientboundAddEntity { - /// Make the entity into a bundle that can be inserted into the ECS. You - /// must apply the metadata after inserting the bundle with + /// Make the entity into a bundle that can be inserted into the ECS. + /// + /// You must apply the metadata after inserting the bundle with /// [`Self::apply_metadata`]. pub fn as_entity_bundle(&self, world_name: ResourceLocation) -> EntityBundle { EntityBundle::new(self.uuid, self.position, self.entity_type, world_name) diff --git a/azalea-protocol/src/packets/game/c_map_item_data.rs b/azalea-protocol/src/packets/game/c_map_item_data.rs index 4bd2b21d..eaf5dc9f 100644 --- a/azalea-protocol/src/packets/game/c_map_item_data.rs +++ b/azalea-protocol/src/packets/game/c_map_item_data.rs @@ -19,7 +19,7 @@ pub struct MapDecoration { pub decoration_type: DecorationType, pub x: i8, pub y: i8, - /// Minecraft does & 15 on this value, azalea-protocol doesn't. I don't + /// Minecraft does `& 15` on this value and azalea-protocol doesn't. I don't /// think it matters. pub rot: i8, pub name: Option, diff --git a/azalea-protocol/src/packets/game/c_player_chat.rs b/azalea-protocol/src/packets/game/c_player_chat.rs index 1e65864c..75683c21 100644 --- a/azalea-protocol/src/packets/game/c_player_chat.rs +++ b/azalea-protocol/src/packets/game/c_player_chat.rs @@ -41,7 +41,7 @@ pub struct PackedLastSeenMessages { pub entries: Vec, } -/// Messages can be deleted by either their signature or message id. +/// Messages can be deleted by either their signature or message ID. #[derive(Clone, Debug, PartialEq)] pub enum PackedMessageSignature { Signature(Box), @@ -88,9 +88,10 @@ pub struct MessageSignatureCache { } impl ClientboundPlayerChat { - /// Returns the content of the message. If you want to get the FormattedText - /// for the whole message including the sender part, use - /// [`ClientboundPlayerChat::message`]. + /// Returns the content of the message. + /// + /// If you want to get the [`FormattedText`] for the whole message including + /// the sender part, use [`ClientboundPlayerChat::message`]. #[must_use] pub fn content(&self) -> FormattedText { self.unsigned_content diff --git a/azalea-protocol/src/packets/game/s_use_item_on.rs b/azalea-protocol/src/packets/game/s_use_item_on.rs index e97d8aaf..61d7fc78 100644 --- a/azalea-protocol/src/packets/game/s_use_item_on.rs +++ b/azalea-protocol/src/packets/game/s_use_item_on.rs @@ -24,9 +24,10 @@ pub struct BlockHit { pub block_pos: BlockPos, /// The face of the block that was clicked. pub direction: Direction, - /// The exact coordinates of the world where the block was clicked. In the - /// network, this is transmitted as the difference between the location and - /// block position. + /// The exact coordinates of the world where the block was clicked. + /// + /// In the network, this is transmitted as the difference between the + /// location and block position. pub location: Vec3, /// Whether the player's head is inside a block. pub inside: bool, diff --git a/azalea-protocol/src/packets/mod.rs b/azalea-protocol/src/packets/mod.rs index e532ebcd..cbcf4d6d 100644 --- a/azalea-protocol/src/packets/mod.rs +++ b/azalea-protocol/src/packets/mod.rs @@ -50,7 +50,7 @@ where /// like `pong`. fn name(&self) -> &'static str; - /// Read a packet by its id, `ConnectionProtocol`, and flow + /// Read a packet by its ID, `ConnectionProtocol`, and flow. fn read(id: u32, buf: &mut Cursor<&[u8]>) -> Result>; fn write(&self, buf: &mut impl Write) -> io::Result<()>; diff --git a/azalea-protocol/src/read.rs b/azalea-protocol/src/read.rs index 433a2718..d4357c9f 100644 --- a/azalea-protocol/src/read.rs +++ b/azalea-protocol/src/read.rs @@ -83,7 +83,7 @@ pub enum FrameSplitterError { } /// Read a length, then read that amount of bytes from the `Cursor>`. If -/// there's not enough data, return None +/// there's not enough data, `None` is returned. fn parse_frame(buffer: &mut Cursor>) -> Result, FrameSplitterError> { // copy the buffer first and read from the copy, then once we make sure // the packet is all good we read it fully @@ -183,8 +183,10 @@ pub enum DecompressionError { AboveCompressionThreshold { size: u32, maximum: u32 }, } -/// Get the decompressed bytes from a packet. It must have been decrypted -/// first. +/// Get the decompressed bytes from a packet. +/// +/// The stream must have already been decrypted before passing it to this +/// function. pub fn compression_decoder( stream: &mut Cursor<&[u8]>, compression_threshold: u32, -- cgit v1.2.3