More documentation updates

Author: leftmostcat

src/types/get_folder.rs

@@ -16,7 +16,11 @@ use crate::{
 #[derive(Debug, XmlSerialize)]
 #[xml_struct(default_ns = MESSAGES_NS_URI)]
 pub struct GetFolder {
+    /// A description of the information to be included in the response for each
+    /// retrieved folder.
     pub folder_shape: FolderShape,
+
+    /// A list of IDs for which to retrieve folder information.
     pub folder_ids: Vec<BaseFolderId>,
 }
 
@@ -62,8 +66,11 @@ pub struct ResponseMessages {
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "PascalCase")]
 pub struct GetFolderResponseMessage {
+    /// The success value of the corresponding request.
     #[serde(rename = "@ResponseClass")]
     pub response_class: ResponseClass,
+
+    /// A collection of the retrieved folders.
     pub folders: Folders,
 }
 

src/types/soap.rs

@@ -14,7 +14,7 @@ use crate::{
 mod de;
 use self::de::DummyEnvelope;
 
-/// A SOAP envelope wrapping an EWS operation.
+/// A SOAP envelope containing the body of an EWS operation or response.
 ///
 /// See <https://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383494>
 #[derive(Debug)]

src/types/sync_folder_hierarchy.rs

@@ -10,14 +10,26 @@ use crate::{
     OperationResponse, ResponseClass, MESSAGES_NS_URI,
 };
 
-/// The request for update regarding the folder hierarchy in a mailbox.
+/// A request for a list of folders which have been created, updated, or deleted
+/// server-side.
 ///
 /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/syncfolderhierarchy>
 #[derive(Debug, XmlSerialize)]
 #[xml_struct(default_ns = MESSAGES_NS_URI)]
 pub struct SyncFolderHierarchy {
+    /// A description of the information to be included in the response for each
+    /// changed folder.
     pub folder_shape: FolderShape,
+
+    /// The ID of the folder to sync.
     pub sync_folder_id: Option<BaseFolderId>,
+
+    /// The synchronization state after which to list changes.
+    ///
+    /// If `None`, the response will include `Create` changes for each folder
+    /// which is a descendant of the requested folder.
+    ///
+    /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/syncstate-ex15websvcsotherref>
     pub sync_state: Option<String>,
 }
 
@@ -31,7 +43,7 @@ impl EnvelopeBodyContents for SyncFolderHierarchy {
     }
 }
 
-/// The response to a SyncFolderHierarchy request.
+/// A response to a [`SyncFolderHierarchy`] request.
 ///
 /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/syncfolderhierarchyresponse>
 #[derive(Debug, Deserialize)]
@@ -48,27 +60,40 @@ impl EnvelopeBodyContents for SyncFolderHierarchyResponse {
     }
 }
 
-/// A collection of response messages from a SyncFolderHierarchy response.
+/// A collection of responses for individual entities within a request.
+///
+/// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/responsemessages>
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "PascalCase")]
 pub struct ResponseMessages {
     pub sync_folder_hierarchy_response_message: Vec<SyncFolderHierarchyResponseMessage>,
 }
 
-/// A message in a SyncFolderHierarchy response.
+/// A response to a request for an individual folder within a [`SyncFolderHierarchy`] operation.
 ///
 /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/syncfolderhierarchyresponsemessage>
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "PascalCase")]
 pub struct SyncFolderHierarchyResponseMessage {
+    /// The success value of the corresponding request.
     #[serde(rename = "@ResponseClass")]
     pub response_class: ResponseClass,
+
+    /// An identifier for the synchronization state following application of the
+    /// changes included in this response.
     pub sync_state: String,
+
+    /// Whether all relevant folder changes have been synchronized following
+    /// this response.
     pub includes_last_folder_in_range: bool,
+
+    /// The collection of changes between the prior synchronization state and
+    /// the one represented by this response.
     pub changes: Changes,
 }
 
-/// The changes that happened since the last folder hierachy sync.
+/// A sequentially-ordered collection of folder creations, updates, and
+/// deletions.
 ///
 /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/changes-hierarchy>
 #[derive(Debug, Deserialize)]
@@ -77,29 +102,34 @@ pub struct Changes {
     pub inner: Vec<Change>,
 }
 
-/// A single change described in a SyncFolderHierarchy response message.
+/// A server-side change to a folder.
 ///
 /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/changes-hierarchy>
 #[derive(Debug, Deserialize)]
 pub enum Change {
-    /// A folder to create.
+    /// A creation of a folder.
     ///
     /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/create-foldersync>
     Create {
+        /// The state of the folder upon creation.
         #[serde(rename = "$value")]
         folder: Folder,
     },
 
-    /// A folder to update.
+    /// An update to a folder.
     ///
     /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/update-foldersync>
     Update {
+        /// The updated state of the folder.
         #[serde(rename = "$value")]
         folder: Folder,
     },
 
-    /// A folder to delete.
+    /// A deletion of a folder.
     ///
     /// See <https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/delete-foldersync>
-    Delete(FolderId),
+    Delete(
+        /// The EWS ID for the deleted folder.
+        FolderId
+    ),
 }