💥 Improve the docs and error handling

src/models/data/base_player_create.rs

@@ -22,8 +22,16 @@ pub struct BasePlayerCreate {
     #[serde(rename(deserialize = "camouflageSlot"))]
     pub camouflage_slot: u8,
 
+    /// Average team ratings for rating battles.
+    ///
+    /// # Contains
+    ///
+    /// - [`Some`] 2-vector, if the attribute is present in the replay. Each element represents one team:
+    ///     - [`Some`] rating, if known
+    ///     - [`None`], if the average rating is unknown (all the players are calibrating)
+    /// - [`None`], if the attribute is missing in the replay
     #[serde(default, rename(deserialize = "avgMmr"))]
-    pub average_mmr: Option<Vec<Option<f64>>>,
+    pub average_mm_ratings: Option<Vec<Option<f64>>>,
 
     #[serde(default, rename(deserialize = "playerWaitTimes"))]
     pub player_wait_times: Option<HashMap<u32, f64>>,
@@ -35,6 +43,10 @@ pub struct BasePlayerCreate {
     pub turbo_battles_statistics: Option<TurboBattlesStatistics>,
 }
 
+/// I don't know what that is:
+///
+/// - On EU, Asia, and NA the values are just constants
+/// - On Russia, the `alpha` and `beta` are different constants, and the chances actually differ for different replays
 #[derive(Debug, Serialize, Deserialize)]
 pub struct TurboBattlesStatistics {
     #[serde(rename(deserialize = "turboBattleChance"))]

src/models/data/entity_method.rs

@@ -26,7 +26,7 @@ pub enum EntityMethod {
 }
 
 impl EntityMethod {
-    /// Parse the entity method payload.
+    /// Parse the entity method raw payload.
     pub fn new(raw_payload: &[u8]) -> Result<Self> {
         let mut raw_payload = raw_payload;
 

src/models/data/packet.rs

@@ -6,6 +6,7 @@ use serde_with::serde_as;
 
 use crate::models::data::payload::Payload;
 use crate::result::Result;
+use crate::Error;
 
 /// «Packet» is a single traffic message in a replay,
 /// packets tell us what is going on during the battle.
@@ -28,14 +29,26 @@ pub struct Packet {
 }
 
 impl Packet {
+    /// Parse next packet from the reader.
+    ///
+    /// # Returns
+    ///
+    /// Parsed packet, or [`None`], when no packets are left.
     pub fn from_reader(reader: &mut impl Read) -> Result<Option<Self>> {
         let Ok(length) = reader.read_u32::<LittleEndian>() else { return Ok(None) };
         let type_ = reader.read_u32::<LittleEndian>()?;
         let clock_secs = reader.read_f32::<LittleEndian>()?;
         let raw_payload = Self::read_raw_payload(reader, length as usize)?;
+        let payload = Payload::new(type_, &raw_payload).map_err(|source| {
+            Error::PacketPayloadParsingError {
+                source: Box::new(source),
+                type_,
+                clock_secs,
+            }
+        })?;
         let this = Self {
             clock_secs,
-            payload: Payload::new(type_, &raw_payload)?,
+            payload,
 
             #[cfg(feature = "raw-payload")]
             raw_payload,

src/models/data/payload.rs

@@ -29,7 +29,7 @@ pub enum Payload {
 }
 
 impl Payload {
-    /// Parse the packet payload.
+    /// Parse the raw packet payload.
     pub fn new(packet_type: u32, raw_payload: &[u8]) -> Result<Self> {
         let mut raw_payload = raw_payload;