Document all fields of GatewayReady and GatewayReadyBot

src/types/events/ready.rs

@@ -14,47 +14,80 @@ use crate::types::{
 };
 
 #[derive(Debug, Deserialize, Serialize, Default, Clone, WebSocketEvent)]
-/// Received after identifying, provides initial user info
+/// Received after identifying, provides initial user information and client state.
 ///
 /// See <https://docs.discord.sex/topics/gateway-events#ready> and <https://discord.com/developers/docs/topics/gateway-events#ready>
 pub struct GatewayReady {
+    #[serde(default)]
+    /// An array of stringified JSON values representing the connection trace, used for debugging
+    pub _trace: Vec<String>,
+    /// The token used for analytical tracking requests
     pub analytics_token: String,
+    /// The hash of the auth session ID corresponding to the auth token used to connect
     pub auth_session_id_hash: String,
+    /// The detected ISO 3166-1 alpha-2 country code of the user's current IP address
     pub country_code: String,
-    pub v: u8,
+    #[serde(rename = "v")]
+    /// API version
+    pub api_version: u8,
+    /// The connected user
     pub user: User,
     #[serde(default)]
+    /// The guilds the user is in
     pub guilds: Vec<Guild>,
+    /// The presences of the user's non-offline friends and implicit relationships (depending on the `NO_AFFINE_USER_IDS` Gateway capability).
     pub presences: Option<Vec<PresenceUpdate>>,
     pub sessions: Option<Vec<Session>>,
+    /// Unique session ID, used for resuming connections
     pub session_id: String,
+    /// The type of session that was started
     pub session_type: String,
+    /// WebSocket URL for resuming connections
     pub resume_gateway_url: String,
+    /// The shard information (shard_id, num_shards) associated with this session, if sharded
     pub shard: Option<(u64, u64)>,
+    /// The client settings for the user
     pub user_settings: Option<UserSettings>,
+    /// The base-64 encoded preloaded user settings for the user, (if missing, defaults are used)
     pub user_settings_proto: Option<String>,
     #[serde(default)]
+    /// The relationships the user has with other users
     pub relationships: Vec<Relationship>,
+    /// The number of friend suggestions the user has
     pub friend_suggestion_count: u32,
     #[serde(default)]
+    /// The DMs and group DMs the user is participating in
     pub private_channels: Vec<Channel>,
     #[serde(default)]
+    /// A mapping of user IDs to notes the user has made for them
     pub notes: HashMap<Snowflake, String>,
+    /// The presences of the user's non-offline friends and implicit relationships (depending on the `NO_AFFINE_USER_IDS` Gateway capability), and any guild presences sent at startup
     pub merged_presences: Option<MergedPresences>,
     #[serde(default)]
+    /// The deduped users across all objects in the event
     pub users: Vec<User>,
+    /// The refreshed auth token for this user; if present, the client should discard the current auth token and use this in subsequent requests to the API
     pub auth_token: Option<String>,
     #[serde(default)]
+    /// The types of multi-factor authenticators the user has enabled
     pub authenticator_types: Vec<AuthenticatorType>,
+    /// The action a user is required to take before continuing to use Discord
     pub required_action: Option<String>,
     #[serde(default)]
+    /// A geo-ordered list of RTC regions that can be used when when setting a voice channel's `rtc_region` or updating the client's voice state
     pub geo_ordered_rtc_regions: Vec<String>,
+    /// The tutorial state of the user, if any
     /// TODO: Make tutorial object into object
     pub tutorial: Option<String>,
+    /// The API code version, used when re-identifying with client state v2
     pub api_code_version: u8,
     #[serde(default)]
+    /// User experiment rollouts for the user
+    /// TODO: Make User Experiments into own struct
     pub experiments: Vec<String>,
     #[serde(default)]
+    /// Guild experiment rollouts for the user
+    /// TODO: Make Guild Experiments into own struct
     pub guild_experiments: Vec<String>,
 }
 
@@ -63,30 +96,49 @@ pub struct GatewayReady {
 ///
 /// See <https://docs.discord.sex/topics/gateway-events#ready> and <https://discord.com/developers/docs/topics/gateway-events#ready>
 pub struct GatewayReadyBot {
-    pub v: u8,
+    #[serde(default)]
+    /// An array of stringified JSON values representing the connection trace, used for debugging
+    pub _trace: Vec<String>,
+    #[serde(rename = "v")]
+    /// API version
+    pub api_version: u8,
+    /// The connected bot user
     pub user: User,
+    #[serde(default)]
+    /// The guilds the bot user is in. Will be `UnavailableGuilds` at first.
     pub guilds: Vec<Guild>,
+    /// The presences of the user's non-offline friends and implicit relationships (depending on the `NO_AFFINE_USER_IDS` Gateway capability).
     pub presences: Option<Vec<PresenceUpdate>>,
-    pub sessions: Option<Vec<Session>>,
+    /// Unique session ID, used for resuming connections
     pub session_id: String,
+    /// The type of session that was started
     pub session_type: String,
+    /// WebSocket URL for resuming connections
     pub resume_gateway_url: String,
+    /// The shard information (shard_id, num_shards) associated with this session, if sharded
     pub shard: Option<(u64, u64)>,
+    /// The presences of the user's non-offline friends and implicit relationships (depending on the `NO_AFFINE_USER_IDS` Gateway capability), and any guild presences sent at startup
     pub merged_presences: Option<MergedPresences>,
+    #[serde(default)]
+    /// The deduped users across all objects in the event
     pub users: Vec<User>,
+    #[serde(default)]
+    /// The types of multi-factor authenticators the user has enabled
     pub authenticator_types: Vec<AuthenticatorType>,
+    #[serde(default)]
+    /// A geo-ordered list of RTC regions that can be used when when setting a voice channel's `rtc_region` or updating the client's voice state
     pub geo_ordered_rtc_regions: Vec<String>,
+    /// The API code version, used when re-identifying with client state v2
     pub api_code_version: u8,
 }
 
 impl From<GatewayReady> for GatewayReadyBot {
     fn from(value: GatewayReady) -> Self {
         GatewayReadyBot {
-            v: value.v,
+            api_version: value.api_version,
             user: value.user,
             guilds: value.guilds,
             presences: value.presences,
-            sessions: value.sessions,
             session_id: value.session_id,
             session_type: value.session_type,
             resume_gateway_url: value.resume_gateway_url,
@@ -96,6 +148,7 @@ impl From<GatewayReady> for GatewayReadyBot {
             authenticator_types: value.authenticator_types,
             geo_ordered_rtc_regions: value.geo_ordered_rtc_regions,
             api_code_version: value.api_code_version,
+            _trace: value._trace,
         }
     }
 }