Apply documentation suggestions from code review

Co-authored-by: Sean Burke <[email protected]>

src/types/common.rs

@@ -523,12 +523,15 @@ pub struct Recipient {
     pub mailbox: Mailbox,
 }
 
-/// A util function to deserialize a list of recipients. This is necessary
-/// because quick-xml's serde data model requires the presence of an
+/// Deserializes a list of recipients.
+///
+/// `quick-xml`'s `serde` implementation requires the presence of an
 /// intermediate type when dealing with lists, and this is not compatible with
-/// our model for serialization. Note that we could directly deserialize into a
-/// Vec<Mailbox>, which would also simplify this function a bit, but this would
-/// mean using different models to represent a single vs multiple recipient(s).
+/// our model for serialization.
+/// 
+/// We could directly deserialize into a `Vec<Mailbox>`, which would also
+/// simplify this function a bit, but this would mean using different models
+/// to represent single vs. multiple recipient(s).
 fn deserialize_recipients<'de, D>(deserializer: D) -> Result<Option<Vec<Recipient>>, D::Error>
 where
     D: Deserializer<'de>,

src/types/create_item.rs

@@ -10,8 +10,7 @@ use crate::{
     ResponseClass, ResponseCode, MESSAGES_NS_URI,
 };
 
-/// Describes how an item is handled once it has been created, if it's a message
-/// item.
+/// The action an Exchange server will take upon creating a `Message` item.
 ///
 /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/createitem#messagedisposition-attribute>
 #[derive(Debug, XmlSerialize)]
@@ -28,22 +27,26 @@ pub enum MessageDisposition {
 #[derive(Debug, XmlSerialize)]
 #[xml_struct(default_ns = MESSAGES_NS_URI)]
 pub struct CreateItem {
-    /// Describes how an item is handled once it has been created, if it's a
-    /// message item.
+    /// The action the Exchange server will take upon creating this item.
+    ///
+    /// This field is required for and only applicable to [`Message`] items.
+    ///
+    /// [`Message`]: `crate::Message`
     ///
     /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/createitem#messagedisposition-attribute>
     #[xml_struct(attribute)]
     pub message_disposition: MessageDisposition,
 
-    /// The folder in which to store an item once it's been created, if it's a
-    /// message item.
+    /// The folder in which to store an item once it has been created.
     ///
-    /// This is ignored if the message disposition is SendOnly.
+    /// This is ignored if `message_disposition` is [`SendOnly`].
     ///
     /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/saveditemfolderid>
+    ///
+    /// [`SendOnly`]: [`MessageDisposition::SendOnly`]
     pub saved_item_folder_id: Option<BaseFolderId>,
 
-    /// The item(s) to create.
+    /// The item or items to create.
     pub items: Items,
 }