Add more documentation

src/events.rs

@@ -1,7 +1,5 @@
 //! # Events specification.
 
-#![allow(missing_docs)]
-
 use std::path::PathBuf;
 
 use async_channel::{self as channel, Receiver, Sender, TrySendError};
@@ -111,6 +109,7 @@ pub struct Event {
     pub typ: EventType,
 }
 
+/// Event payload.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 pub enum EventType {
     /// The library-user may write an informational string to the log.
@@ -171,17 +170,23 @@ pub enum EventType {
     /// - Chats created, deleted or archived
     /// - A draft has been set
     ///
-    /// `chat_id` is set if only a single chat is affected by the changes, otherwise 0.
-    /// `msg_id` is set if only a single message is affected by the changes, otherwise 0.
     MsgsChanged {
+        /// Set if only a single chat is affected by the changes, otherwise 0.
         chat_id: ChatId,
+
+        /// Set if only a single message is affected by the changes, otherwise 0.
         msg_id: MsgId,
     },
 
     /// Reactions for the message changed.
     ReactionsChanged {
+        /// ID of the chat which the message belongs to.
         chat_id: ChatId,
+
+        /// ID of the message for which reactions were changed.
         msg_id: MsgId,
+
+        /// ID of the contact whose reaction set is changed.
         contact_id: ContactId,
     },
 
@@ -190,11 +195,16 @@ pub enum EventType {
     ///
     /// There is no extra #DC_EVENT_MSGS_CHANGED event send together with this event.
     IncomingMsg {
+        /// ID of the chat where the message is assigned.
         chat_id: ChatId,
+
+        /// ID of the message.
         msg_id: MsgId,
     },
 
+    /// Downloading a bunch of messages just finished.
     IncomingMsgBunch {
+        /// List of incoming message IDs.
         msg_ids: Vec<MsgId>,
     },
 
@@ -205,21 +215,30 @@ pub enum EventType {
     /// A single message is sent successfully. State changed from  DC_STATE_OUT_PENDING to
     /// DC_STATE_OUT_DELIVERED, see dc_msg_get_state().
     MsgDelivered {
+        /// ID of the chat which the message belongs to.
         chat_id: ChatId,
+
+        /// ID of the message that was successfully sent.
         msg_id: MsgId,
     },
 
     /// A single message could not be sent. State changed from DC_STATE_OUT_PENDING or DC_STATE_OUT_DELIVERED to
     /// DC_STATE_OUT_FAILED, see dc_msg_get_state().
     MsgFailed {
+        /// ID of the chat which the message belongs to.
         chat_id: ChatId,
+
+        /// ID of the message that could not be sent.
         msg_id: MsgId,
     },
 
     /// A single message is read by the receiver. State changed from DC_STATE_OUT_DELIVERED to
     /// DC_STATE_OUT_MDN_RCVD, see dc_msg_get_state().
     MsgRead {
+        /// ID of the chat which the message belongs to.
         chat_id: ChatId,
+
+        /// ID of the message that was read.
         msg_id: MsgId,
     },
 
@@ -234,7 +253,10 @@ pub enum EventType {
 
     /// Chat ephemeral timer changed.
     ChatEphemeralTimerModified {
+        /// Chat ID.
         chat_id: ChatId,
+
+        /// New ephemeral timer value.
         timer: EphemeralTimer,
     },
 
@@ -281,15 +303,15 @@ pub enum EventType {
     ///
     /// These events are typically sent after a joiner has scanned the QR code
     /// generated by dc_get_securejoin_qr().
-    ///
-    /// @param data1 (int) ID of the contact that wants to join.
-    /// @param data2 (int) Progress as:
-    ///     300=vg-/vc-request received, typically shown as "bob@addr joins".
-    ///     600=vg-/vc-request-with-auth received, vg-member-added/vc-contact-confirm sent, typically shown as "bob@addr verified".
-    ///     800=contact added to chat, shown as "bob@addr securely joined GROUP". Only for the verified-group-protocol.
-    ///     1000=Protocol finished for this contact.
     SecurejoinInviterProgress {
+        /// ID of the contact that wants to join.
         contact_id: ContactId,
+
+        /// Progress as:
+        /// 300=vg-/vc-request received, typically shown as "bob@addr joins".
+        /// 600=vg-/vc-request-with-auth received, vg-member-added/vc-contact-confirm sent, typically shown as "bob@addr verified".
+        /// 800=contact added to chat, shown as "bob@addr securely joined GROUP". Only for the verified-group-protocol.
+        /// 1000=Protocol finished for this contact.
         progress: usize,
     },
 
@@ -297,12 +319,13 @@ pub enum EventType {
     /// (Bob, the person who scans the QR code).
     /// The events are typically sent while dc_join_securejoin(), which
     /// may take some time, is executed.
-    /// @param data1 (int) ID of the inviting contact.
-    /// @param data2 (int) Progress as:
-    ///     400=vg-/vc-request-with-auth sent, typically shown as "alice@addr verified, introducing myself."
-    ///     (Bob has verified alice and waits until Alice does the same for him)
     SecurejoinJoinerProgress {
+        /// ID of the inviting contact.
         contact_id: ContactId,
+
+        /// Progress as:
+        /// 400=vg-/vc-request-with-auth sent, typically shown as "alice@addr verified, introducing myself."
+        /// (Bob has verified alice and waits until Alice does the same for him)
         progress: usize,
     },
 
@@ -312,15 +335,21 @@ pub enum EventType {
     /// dc_get_connectivity_html() for details.
     ConnectivityChanged,
 
+    /// The user's avatar changed.
     SelfavatarChanged,
 
+    /// Webxdc status update received.
     WebxdcStatusUpdate {
+        /// Message ID.
         msg_id: MsgId,
+
+        /// Status update ID.
         status_update_serial: StatusUpdateSerial,
     },
 
-    /// Inform that a message containing a webxdc instance has been deleted
+    /// Inform that a message containing a webxdc instance has been deleted.
     WebxdcInstanceDeleted {
+        /// ID of the deleted message.
         msg_id: MsgId,
     },
 }