Improve OCamldoc documentation in library interfaces

- Add detailed documentation for all types and functions in jmap.mli
- Add detailed documentation for all types and functions in jmap_mail.mli
- Include proper @see references with URLs to RFC sections
- Include field-level documentation for record types
- Follow OCamldoc standards with proper parameter documentation

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[e-mail]>

lib/jmap.mli

···
 (**
  * JMAP protocol implementation based on RFC8620
  * https://datatracker.ietf.org/doc/html/rfc8620
+ *
+ * This module implements the core JMAP protocol as defined in RFC8620, providing
+ * types and functions for making JMAP API requests and handling responses.
  *)
 
-(** Initialize and configure logging for JMAP *)
+(** Initialize and configure logging for JMAP
+    @param level Optional logging level (higher means more verbose)
+    @param enable_logs Whether to enable logging at all (default true)
+    @param redact_sensitive Whether to redact sensitive information like tokens (default true)
+ *)
 val init_logging : ?level:int -> ?enable_logs:bool -> ?redact_sensitive:bool -> unit -> unit
 
-(** Redact sensitive data like tokens *)
+(** Redact sensitive data like authentication tokens from logs
+    @param redact Whether to perform redaction (default true)
+    @param token The token string to redact
+    @return A redacted version of the token (with characters replaced by '*')
+ *)
 val redact_token : ?redact:bool -> string -> string
 
-(** Module for managing JMAP capability URIs and other constants *)
+(** Module for managing JMAP capability URIs and other constants 
+    as defined in RFC8620 Section 1.8
+    @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.8> RFC8620 Section 1.8
+*)
 module Capability : sig
-  (** JMAP capability URI as specified in RFC8620 *)
+  (** JMAP core capability URI as specified in RFC8620 Section 2
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2> RFC8620 Section 2
+  *)
   val core_uri : string
 
-  (** All JMAP capability types *)
+  (** All JMAP capability types as described in RFC8620 Section 1.8
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.8> RFC8620 Section 1.8
+  *)
   type t = 
     | Core       (** Core JMAP capability *)
-    | Extension of string  (** Extension capabilities *)
+    | Extension of string  (** Extension capabilities with custom URIs *)
 
-  (** Convert capability to URI string *)
+  (** Convert capability to URI string
+      @param capability The capability to convert
+      @return The full URI string for the capability
+  *)
   val to_string : t -> string
 
-  (** Parse a string to a capability, returns Extension for non-core capabilities *)
+  (** Parse a string to a capability, returns Extension for non-core capabilities
+      @param uri The capability URI string to parse
+      @return The parsed capability type
+  *)
   val of_string : string -> t
     
-  (** Check if a capability matches a core capability *)
+  (** Check if a capability matches the core capability
+      @param capability The capability to check
+      @return True if the capability is the core JMAP capability
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
+  *)
   val is_core : t -> bool
 
-  (** Check if a capability string is a core capability *)
+  (** Check if a capability string is the core capability URI
+      @param uri The capability URI string to check
+      @return True if the string represents the core JMAP capability
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
+  *)
   val is_core_string : string -> bool
 
-  (** Create a list of capability strings *)
+  (** Create a list of capability URI strings
+      @param capabilities List of capability types
+      @return List of capability URI strings
+  *)
   val strings_of_capabilities : t list -> string list
 end
 
-(** {1 Types} *)
+(** {1 Types}
+    Core types as defined in RFC8620
+    @see <https://datatracker.ietf.org/doc/html/rfc8620> RFC8620
+*)
 
 module Types : sig
-  (** Id string as per Section 1.2 *)
+  (** Id string as defined in RFC8620 Section 1.2.
+      A string of at least 1 and maximum 255 octets, case-sensitive, 
+      and does not begin with the '#' character.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.2>
+  *)
   type id = string
 
-  (** Int bounded within the range -2^53+1 to 2^53-1 as per Section 1.3 *)
+  (** Int type bounded within the range -2^53+1 to 2^53-1 as defined in RFC8620 Section 1.3.
+      Represented as JSON number where the value MUST be an integer and in the range.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.3>
+  *)
   type int_t = int
 
-  (** UnsignedInt bounded within the range 0 to 2^53-1 as per Section 1.3 *)
+  (** UnsignedInt bounded within the range 0 to 2^53-1 as defined in RFC8620 Section 1.3.
+      Represented as JSON number where the value MUST be a non-negative integer and in the range.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.3>
+  *)
   type unsigned_int = int
 
-  (** Date string in RFC3339 format as per Section 1.4 *)
+  (** Date string in RFC3339 format as defined in RFC8620 Section 1.4.
+      Includes date, time and time zone offset information or UTC.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.4>
+  *)
   type date = string
 
-  (** UTCDate is a Date with 'Z' time zone as per Section 1.4 *)
+  (** UTCDate is a Date with 'Z' time zone (UTC) as defined in RFC8620 Section 1.4.
+      Same format as Date type but always with UTC time zone (Z).
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.4>
+  *)
   type utc_date = string
 
-  (** Error object as per Section 3.6.2 *)
+  (** Error object as defined in RFC8620 Section 3.6.2.
+      Used to represent standard error conditions in method responses.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.6.2>
+  *)
   type error = {
-    type_: string;
-    description: string option;
+    type_: string;  (** The type of error, e.g., "serverFail" *)
+    description: string option;  (** Optional human-readable description of the error *)
   }
 
-  (** Set error object as per Section 5.3 *)
+  (** Set error object as defined in RFC8620 Section 5.3.
+      Used for reporting errors in set operations.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
+  *)
   type set_error = {
-    type_: string;
-    description: string option;
-    properties: string list option;
-    (* Additional properties for specific error types *)
-    existing_id: id option; (* For alreadyExists error *)
+    type_: string;  (** The type of error, e.g., "notFound" *)
+    description: string option;  (** Optional human-readable description of the error *)
+    properties: string list option;  (** Properties causing the error, if applicable *)
+    existing_id: id option;  (** For "alreadyExists" error, the ID of the existing object *)
   }
 
-  (** Invocation object as per Section 3.2 *)
+  (** Invocation object as defined in RFC8620 Section 3.2.
+      Represents a method call in the JMAP protocol.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.2>
+  *)
   type 'a invocation = {
-    name: string;
-    arguments: 'a;
-    method_call_id: string;
+    name: string;  (** The name of the method to call, e.g., "Mailbox/get" *)
+    arguments: 'a;  (** The arguments for the method, type varies by method *)
+    method_call_id: string;  (** Client-specified ID for referencing this call *)
   }
 
-  (** ResultReference object as per Section 3.7 *)
+  (** ResultReference object as defined in RFC8620 Section 3.7.
+      Used to reference results from previous method calls.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.7>
+  *)
   type result_reference = {
-    result_of: string;
-    name: string;
-    path: string;
+    result_of: string;  (** The method_call_id of the method to reference *)
+    name: string;  (** Name of the response in the referenced result *)
+    path: string;  (** JSON pointer path to the value being referenced *)
   }
 
-  (** FilterOperator, FilterCondition and Filter as per Section 5.5 *)
+  (** FilterOperator, FilterCondition and Filter as defined in RFC8620 Section 5.5.
+      Used for complex filtering in query methods.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
+  *)
   type filter_operator = {
-    operator: string; (* "AND", "OR", "NOT" *)
-    conditions: filter list;
+    operator: string;  (** The operator: "AND", "OR", "NOT" *)
+    conditions: filter list;  (** The conditions to apply the operator to *)
   }
-  and filter_condition = (string * Ezjsonm.value) list
+ 
+  (** Property/value pairs for filtering *)
+  and filter_condition =
+    (string * Ezjsonm.value) list 
+
   and filter = 
-    | Operator of filter_operator
-    | Condition of filter_condition
+    | Operator of filter_operator  (** Logical operator combining conditions *)
+    | Condition of filter_condition  (** Simple property-based condition *)
 
-  (** Comparator object for sorting as per Section 5.5 *)
+  (** Comparator object for sorting as defined in RFC8620 Section 5.5.
+      Specifies how to sort query results.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
+  *)
   type comparator = {
-    property: string;
-    is_ascending: bool option; (* Optional, defaults to true *)
-    collation: string option;  (* Optional, server-dependent default *)
+    property: string;  (** The property to sort by *)
+    is_ascending: bool option;  (** Sort order (true for ascending, false for descending) *)
+    collation: string option;  (** Collation algorithm for string comparison *)
   }
 
-  (** PatchObject as per Section 5.3 *)
-  type patch_object = (string * Ezjsonm.value) list
+  (** PatchObject as defined in RFC8620 Section 5.3.
+      Used to represent a set of updates to apply to an object.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
+  *)
+  type patch_object = (string * Ezjsonm.value) list  (** List of property/value pairs to update *)
 
-  (** AddedItem structure as per Section 5.6 *)
+  (** AddedItem structure as defined in RFC8620 Section 5.6.
+      Represents an item added to a query result.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.6>
+  *)
   type added_item = {
-    id: id;
-    index: unsigned_int;
+    id: id;  (** The ID of the added item *)
+    index: unsigned_int;  (** The index in the result list where the item appears *)
   }
 
-  (** Account object as per Section 1.6.2 *)
+  (** Account object as defined in RFC8620 Section 1.6.2.
+      Represents a user account in JMAP.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.6.2>
+  *)
   type account = {
-    name: string;
-    is_personal: bool;
-    is_read_only: bool;
-    account_capabilities: (string * Ezjsonm.value) list;
+    name: string;  (** User-friendly account name, e.g. "[e-mail]" *)
+    is_personal: bool;  (** Whether this account belongs to the authenticated user *)
+    is_read_only: bool;  (** Whether this account can be modified *)
+    account_capabilities: (string * Ezjsonm.value) list;  (** Capabilities available for this account *)
   }
 
-  (** Core capability object as per Section 2 *)
+  (** Core capability object as defined in RFC8620 Section 2.
+      Describes limits and features of the JMAP server.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
+  *)
   type core_capability = {
-    max_size_upload: unsigned_int;
-    max_concurrent_upload: unsigned_int;
-    max_size_request: unsigned_int;
-    max_concurrent_requests: unsigned_int;
-    max_calls_in_request: unsigned_int;
-    max_objects_in_get: unsigned_int;
-    max_objects_in_set: unsigned_int;
-    collation_algorithms: string list;
+    max_size_upload: unsigned_int;  (** Maximum file size in octets for uploads *)
+    max_concurrent_upload: unsigned_int;  (** Maximum number of concurrent uploads *)
+    max_size_request: unsigned_int;  (** Maximum size in octets for a request *)
+    max_concurrent_requests: unsigned_int;  (** Maximum number of concurrent requests *)
+    max_calls_in_request: unsigned_int;  (** Maximum number of method calls in a request *)
+    max_objects_in_get: unsigned_int;  (** Maximum number of objects in a get request *)
+    max_objects_in_set: unsigned_int;  (** Maximum number of objects in a set request *)
+    collation_algorithms: string list;  (** Supported string collation algorithms *)
   }
 
-  (** PushSubscription keys object as per Section 7.2 *)
+  (** PushSubscription keys object as defined in RFC8620 Section 7.2.
+      Contains encryption keys for web push subscriptions.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.2>
+  *)
   type push_keys = {
-    p256dh: string;
-    auth: string;
+    p256dh: string;  (** User agent public key (Base64url-encoded) *)
+    auth: string;  (** Authentication secret (Base64url-encoded) *)
   }
 
-  (** Session object as per Section 2 *)
+  (** Session object as defined in RFC8620 Section 2.
+      Contains information about the server and user's accounts.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
+  *)
   type session = {
-    capabilities: (string * Ezjsonm.value) list;
-    accounts: (id * account) list;
-    primary_accounts: (string * id) list;
-    username: string;
-    api_url: string;
-    download_url: string;
-    upload_url: string;
-    event_source_url: string option;
-    state: string;
+    capabilities: (string * Ezjsonm.value) list;  (** Server capabilities with their properties *)
+    accounts: (id * account) list;  (** Map of account IDs to account objects *)
+    primary_accounts: (string * id) list;  (** Map of capability URIs to primary account IDs *)
+    username: string;  (** Username associated with this session *)
+    api_url: string;  (** URL to use for JMAP API requests *)
+    download_url: string;  (** URL endpoint to download files *)
+    upload_url: string;  (** URL endpoint to upload files *)
+    event_source_url: string option;  (** URL for Server-Sent Events notifications *)
+    state: string;  (** String representing the state on the server *)
   }
 
-  (** TypeState for state changes as per Section 7.1 *)
-  type type_state = (string * string) list
+  (** TypeState for state changes as defined in RFC8620 Section 7.1.
+      Maps data type names to the state string for that type.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.1>
+  *)
+  type type_state = (string * string) list  (** (data type name, state string) pairs *)
 
-  (** StateChange object as per Section 7.1 *)
+  (** StateChange object as defined in RFC8620 Section 7.1.
+      Represents changes to data types for different accounts.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.1>
+  *)
   type state_change = {
-    changed: (id * type_state) list;
+    changed: (id * type_state) list;  (** Map of account IDs to type state changes *)
   }
 
-  (** PushVerification object as per Section 7.2.2 *)
+  (** PushVerification object as defined in RFC8620 Section 7.2.2.
+      Used for verifying push subscription ownership.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.2.2>
+  *)
   type push_verification = {
-    push_subscription_id: id;
-    verification_code: string;
+    push_subscription_id: id;  (** ID of the push subscription being verified *)
+    verification_code: string;  (** Code the client must submit to verify ownership *)
   }
 
-  (** PushSubscription object as per Section 7.2 *)
+  (** PushSubscription object as defined in RFC8620 Section 7.2.
+      Represents a subscription for push notifications.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.2>
+  *)
   type push_subscription = {
-    id: id;
-    device_client_id: string;
-    url: string;
-    keys: push_keys option;
-    verification_code: string option;
-    expires: utc_date option;
-    types: string list option;
+    id: id;  (** Server-assigned ID for the subscription *)
+    device_client_id: string;  (** ID representing the client/device *)
+    url: string;  (** URL to which events are pushed *)
+    keys: push_keys option;  (** Encryption keys for web push, if any *)
+    verification_code: string option;  (** Verification code if not yet verified *)
+    expires: utc_date option;  (** When the subscription expires, if applicable *)
+    types: string list option;  (** Types of changes to push, null means all *)
   }
 
-  (** Request object as per Section 3.3 *)
+  (** Request object as defined in RFC8620 Section 3.3.
+      Represents a JMAP request from client to server.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.3>
+  *)
   type request = {
-    using: string list;
-    method_calls: Ezjsonm.value invocation list;
-    created_ids: (id * id) list option;
+    using: string list;  (** Capabilities required for this request *)
+    method_calls: Ezjsonm.value invocation list;  (** List of method calls to process *)
+    created_ids: (id * id) list option;  (** Map of client-created IDs to server IDs *)
   }
 
-  (** Response object as per Section 3.4 *)
+  (** Response object as defined in RFC8620 Section 3.4.
+      Represents a JMAP response from server to client.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.4>
+  *)
   type response = {
-    method_responses: Ezjsonm.value invocation list;
-    created_ids: (id * id) list option;
-    session_state: string;
+    method_responses: Ezjsonm.value invocation list;  (** List of method responses *)
+    created_ids: (id * id) list option;  (** Map of client-created IDs to server IDs *)
+    session_state: string;  (** Current session state on the server *)
   }
 
-  (** Standard method arguments and responses *)
+  (** {2 Standard method arguments and responses}
+      Standard method patterns defined in RFC8620 Section 5
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5>
+  *)
 
-  (** Arguments for Foo/get method as per Section 5.1 *)
+  (** Arguments for Foo/get method as defined in RFC8620 Section 5.1.
+      Generic template for retrieving objects by ID.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.1>
+  *)
   type 'a get_arguments = {
-    account_id: id;
-    ids: id list option;
-    properties: string list option;
+    account_id: id;  (** The account ID to operate on *)
+    ids: id list option;  (** IDs to fetch, null means all *)
+    properties: string list option;  (** Properties to return, null means all *)
   }
 
-  (** Response for Foo/get method as per Section 5.1 *)
+  (** Response for Foo/get method as defined in RFC8620 Section 5.1.
+      Generic template for returning requested objects.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.1>
+  *)
   type 'a get_response = {
-    account_id: id;
-    state: string;
-    list: 'a list;
-    not_found: id list;
+    account_id: id;  (** The account ID that was operated on *)
+    state: string;  (** Server state for the type at the time of processing *)
+    list: 'a list;  (** The list of requested objects *)
+    not_found: id list;  (** IDs that could not be found *)
   }
 
-  (** Arguments for Foo/changes method as per Section 5.2 *)
+  (** Arguments for Foo/changes method as defined in RFC8620 Section 5.2.
+      Generic template for getting state changes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.2>
+  *)
   type changes_arguments = {
-    account_id: id;
-    since_state: string;
-    max_changes: unsigned_int option;
+    account_id: id;  (** The account ID to operate on *)
+    since_state: string;  (** The last state seen by the client *)
+    max_changes: unsigned_int option;  (** Maximum number of changes to return *)
   }
 
-  (** Response for Foo/changes method as per Section 5.2 *)
+  (** Response for Foo/changes method as defined in RFC8620 Section 5.2.
+      Generic template for returning object changes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.2>
+  *)
   type changes_response = {
-    account_id: id;
-    old_state: string;
-    new_state: string;
-    has_more_changes: bool;
-    created: id list;
-    updated: id list;
-    destroyed: id list;
+    account_id: id;  (** The account ID that was operated on *)
+    old_state: string;  (** The state provided in the request *)
+    new_state: string;  (** The current server state *)
+    has_more_changes: bool;  (** True if more changes are available *)
+    created: id list;  (** IDs of objects created since old_state *)
+    updated: id list;  (** IDs of objects updated since old_state *)
+    destroyed: id list;  (** IDs of objects destroyed since old_state *)
   }
 
-  (** Arguments for Foo/set method as per Section 5.3 *)
+  (** Arguments for Foo/set method as defined in RFC8620 Section 5.3.
+      Generic template for creating, updating, and destroying objects.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
+  *)
   type 'a set_arguments = {
-    account_id: id;
-    if_in_state: string option;
-    create: (id * 'a) list option;
-    update: (id * patch_object) list option;
-    destroy: id list option;
+    account_id: id;  (** The account ID to operate on *)
+    if_in_state: string option;  (** Only apply changes if in this state *)
+    create: (id * 'a) list option;  (** Map of creation IDs to objects to create *)
+    update: (id * patch_object) list option;  (** Map of IDs to patches to apply *)
+    destroy: id list option;  (** List of IDs to destroy *)
   }
 
-  (** Response for Foo/set method as per Section 5.3 *)
+  (** Response for Foo/set method as defined in RFC8620 Section 5.3.
+      Generic template for reporting create/update/destroy status.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
+  *)
   type 'a set_response = {
-    account_id: id;
-    old_state: string option;
-    new_state: string;
-    created: (id * 'a) list option;
-    updated: (id * 'a option) list option;
-    destroyed: id list option;
-    not_created: (id * set_error) list option;
-    not_updated: (id * set_error) list option;
-    not_destroyed: (id * set_error) list option;
+    account_id: id;  (** The account ID that was operated on *)
+    old_state: string option;  (** The state before processing, if changed *)
+    new_state: string;  (** The current server state *)
+    created: (id * 'a) list option;  (** Map of creation IDs to created objects *)
+    updated: (id * 'a option) list option;  (** Map of IDs to updated objects *)
+    destroyed: id list option;  (** List of IDs successfully destroyed *)
+    not_created: (id * set_error) list option;  (** Map of IDs to errors for failed creates *)
+    not_updated: (id * set_error) list option;  (** Map of IDs to errors for failed updates *)
+    not_destroyed: (id * set_error) list option;  (** Map of IDs to errors for failed destroys *)
   }
 
-  (** Arguments for Foo/copy method as per Section 5.4 *)
+  (** Arguments for Foo/copy method as defined in RFC8620 Section 5.4.
+      Generic template for copying objects between accounts.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.4>
+  *)
   type 'a copy_arguments = {
-    from_account_id: id;
-    if_from_in_state: string option;
-    account_id: id;
-    if_in_state: string option;
-    create: (id * 'a) list;
-    on_success_destroy_original: bool option;
-    destroy_from_if_in_state: string option;
+    from_account_id: id;  (** The account ID to copy from *)
+    if_from_in_state: string option;  (** Only copy if source account in this state *)
+    account_id: id;  (** The account ID to copy to *)
+    if_in_state: string option;  (** Only copy if destination account in this state *)
+    create: (id * 'a) list;  (** Map of creation IDs to objects to copy *)
+    on_success_destroy_original: bool option;  (** Whether to destroy the original after copying *)
+    destroy_from_if_in_state: string option;  (** Only destroy originals if in this state *)
   }
 
-  (** Response for Foo/copy method as per Section 5.4 *)
+  (** Response for Foo/copy method as defined in RFC8620 Section 5.4.
+      Generic template for reporting copy operation status.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.4>
+  *)
   type 'a copy_response = {
-    from_account_id: id;
-    account_id: id;
-    old_state: string option;
-    new_state: string;
-    created: (id * 'a) list option;
-    not_created: (id * set_error) list option;
+    from_account_id: id;  (** The account ID that was copied from *)
+    account_id: id;  (** The account ID that was copied to *)
+    old_state: string option;  (** The state before processing, if changed *)
+    new_state: string;  (** The current server state *)
+    created: (id * 'a) list option;  (** Map of creation IDs to created objects *)
+    not_created: (id * set_error) list option;  (** Map of IDs to errors for failed copies *)
   }
 
-  (** Arguments for Foo/query method as per Section 5.5 *)
+  (** Arguments for Foo/query method as defined in RFC8620 Section 5.5.
+      Generic template for querying objects.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
+  *)
   type query_arguments = {
-    account_id: id;
-    filter: filter option;
-    sort: comparator list option;
-    position: int_t option;
-    anchor: id option;
-    anchor_offset: int_t option;
-    limit: unsigned_int option;
-    calculate_total: bool option;
+    account_id: id;  (** The account ID to operate on *)
+    filter: filter option;  (** Filter to determine which objects are returned *)
+    sort: comparator list option;  (** Sort order for returned objects *)
+    position: int_t option;  (** Zero-based index of first result to return *)
+    anchor: id option;  (** ID of object to use as reference point *)
+    anchor_offset: int_t option;  (** Offset from anchor to start returning results *)
+    limit: unsigned_int option;  (** Maximum number of results to return *)
+    calculate_total: bool option;  (** Whether to calculate the total number of matching objects *)
   }
 
-  (** Response for Foo/query method as per Section 5.5 *)
+  (** Response for Foo/query method as defined in RFC8620 Section 5.5.
+      Generic template for returning query results.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
+  *)
   type query_response = {
-    account_id: id;
-    query_state: string;
-    can_calculate_changes: bool;
-    position: unsigned_int;
-    ids: id list;
-    total: unsigned_int option;
-    limit: unsigned_int option;
+    account_id: id;  (** The account ID that was operated on *)
+    query_state: string;  (** State string for the query results *)
+    can_calculate_changes: bool;  (** Whether queryChanges can be used with these results *)
+    position: unsigned_int;  (** Zero-based index of the first result *)
+    ids: id list;  (** The list of IDs for objects matching the query *)
+    total: unsigned_int option;  (** Total number of matching objects, if calculated *)
+    limit: unsigned_int option;  (** Limit enforced on the results, if requested *)
   }
 
-  (** Arguments for Foo/queryChanges method as per Section 5.6 *)
+  (** Arguments for Foo/queryChanges method as defined in RFC8620 Section 5.6.
+      Generic template for getting query result changes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.6>
+  *)
   type query_changes_arguments = {
-    account_id: id;
-    filter: filter option;
-    sort: comparator list option;
-    since_query_state: string;
-    max_changes: unsigned_int option;
-    up_to_id: id option;
-    calculate_total: bool option;
+    account_id: id;  (** The account ID to operate on *)
+    filter: filter option;  (** Same filter as used in the original query *)
+    sort: comparator list option;  (** Same sort as used in the original query *)
+    since_query_state: string;  (** The query_state from previous results *)
+    max_changes: unsigned_int option;  (** Maximum number of changes to return *)
+    up_to_id: id option;  (** Only calculate changes until this ID is encountered *)
+    calculate_total: bool option;  (** Whether to recalculate the total matches *)
   }
 
-  (** Response for Foo/queryChanges method as per Section 5.6 *)
+  (** Response for Foo/queryChanges method as defined in RFC8620 Section 5.6.
+      Generic template for returning query result changes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.6>
+  *)
   type query_changes_response = {
-    account_id: id;
-    old_query_state: string;
-    new_query_state: string;
-    total: unsigned_int option;
-    removed: id list;
-    added: added_item list option;
+    account_id: id;  (** The account ID that was operated on *)
+    old_query_state: string;  (** The query_state from the request *)
+    new_query_state: string;  (** The current query_state on the server *)
+    total: unsigned_int option;  (** Updated total number of matches, if calculated *)
+    removed: id list;  (** IDs that were in the old results but not in the new *)
+    added: added_item list option;  (** IDs that are in the new results but not the old *)
   }
 
-  (** Arguments for Blob/copy method as per Section 6.3 *)
+  (** Arguments for Blob/copy method as defined in RFC8620 Section 6.3.
+      Used for copying binary data between accounts.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.3>
+  *)
   type blob_copy_arguments = {
-    from_account_id: id;
-    account_id: id;
-    blob_ids: id list;
+    from_account_id: id;  (** The account ID to copy blobs from *)
+    account_id: id;  (** The account ID to copy blobs to *)
+    blob_ids: id list;  (** IDs of blobs to copy *)
   }
 
-  (** Response for Blob/copy method as per Section 6.3 *)
+  (** Response for Blob/copy method as defined in RFC8620 Section 6.3.
+      Reports the results of copying binary data.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.3>
+  *)
   type blob_copy_response = {
-    from_account_id: id;
-    account_id: id;
-    copied: (id * id) list option;
-    not_copied: (id * set_error) list option;
+    from_account_id: id;  (** The account ID that was copied from *)
+    account_id: id;  (** The account ID that was copied to *)
+    copied: (id * id) list option;  (** Map of source IDs to destination IDs *)
+    not_copied: (id * set_error) list option;  (** Map of IDs to errors for failed copies *)
   }
 
-  (** Upload response as per Section 6.1 *)
+  (** Upload response as defined in RFC8620 Section 6.1.
+      Contains information about an uploaded binary blob.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.1>
+  *)
   type upload_response = {
-    account_id: id;
-    blob_id: id;
-    type_: string;
-    size: unsigned_int;
+    account_id: id;  (** The account ID the blob was uploaded to *)
+    blob_id: id;  (** The ID for the uploaded blob *)
+    type_: string;  (** Media type of the blob *)
+    size: unsigned_int;  (** Size of the blob in octets *)
   }
 
-  (** Problem details object as per RFC7807 and Section 3.6.1 *)
+  (** Problem details object as defined in RFC8620 Section 3.6.1 and RFC7807.
+      Used for HTTP error responses in the JMAP protocol.
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.6.1>
+      @see <https://datatracker.ietf.org/doc/html/rfc7807>
+  *)
   type problem_details = {
-    type_: string;
-    status: int option;
-    detail: string option;
-    limit: string option; (* For "limit" error *)
+    type_: string;  (** URI that identifies the problem type *)
+    status: int option;  (** HTTP status code for this problem *)
+    detail: string option;  (** Human-readable explanation of the problem *)
+    limit: string option;  (** For "limit" errors, which limit was exceeded *)
   }
 end
 
-(** {1 API Client} *)
+(** {1 API Client}
+    Modules for interacting with JMAP servers
+*)
 
 (** Module for working with ResultReferences as described in Section 3.7 of RFC8620.
-    Provides utilities to create and compose results from previous methods. *)
+    Provides utilities to create and compose results from previous methods.
+    @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.7>
+*)
 module ResultReference : sig
-  (** Create a reference to a previous method result *)
+  (** Create a reference to a previous method result
+      @param result_of The methodCallId of the method call to reference
+      @param name The name in the response to reference (e.g., "list")
+      @param path JSON pointer path to the value being referenced
+      @return A result_reference object
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.7>
+  *)
   val create : 
     result_of:string ->
     name:string ->
     path:string ->
     Types.result_reference
 
-  (** Create a JSON pointer path to access a specific property *)
+  (** Create a JSON pointer path to access a specific property
+      @param property The property name to access
+      @return A JSON pointer path string
+  *)
   val property_path : string -> string
   
-  (** Create a JSON pointer path to access all items in an array with a specific property *)
+  (** Create a JSON pointer path to access all items in an array with a specific property
+      @param property Optional property to access within each array item
+      @param array_name The name of the array to access
+      @return A JSON pointer path string that references all items in the array
+  *)
   val array_items_path : ?property:string -> string -> string
   
   (** Create argument with result reference.
-      Returns string key prefixed with # and ResultReference value. *)
+      @param arg_name The name of the argument
+      @param reference The result reference to use
+      @return A tuple of string key (with # prefix) and ResultReference JSON value
+  *)
   val reference_arg : string -> Types.result_reference -> string * Ezjsonm.value
   
-  (** Create a reference to all IDs returned by a query method *)
+  (** Create a reference to all IDs returned by a query method
+      @param result_of The methodCallId of the query method call
+      @return A result_reference to the IDs returned by the query
+  *)
   val query_ids :
     result_of:string ->
     Types.result_reference
     
-  (** Create a reference to properties of objects returned by a get method *)
+  (** Create a reference to properties of objects returned by a get method
+      @param result_of The methodCallId of the get method call
+      @param property The property to reference in the returned objects
+      @return A result_reference to the specified property in the get results
+  *)
   val get_property :
     result_of:string ->
     property:string ->
···
 end
 
 (** Module for making JMAP API requests over HTTP.
-    Provides functionality to interact with JMAP servers according to RFC8620. *)
+    Provides functionality to interact with JMAP servers according to RFC8620.
+    @see <https://datatracker.ietf.org/doc/html/rfc8620>
+*)
 module Api : sig
   (** Error that may occur during API requests *)
   type error =
-    | Connection_error of string
-    | HTTP_error of int * string
-    | Parse_error of string
-    | Authentication_error
+    | Connection_error of string   (** Network-related errors *)
+    | HTTP_error of int * string   (** HTTP errors with status code and message *)
+    | Parse_error of string        (** JSON parsing errors *)
+    | Authentication_error         (** Authentication failures *)
   
   (** Result type for API operations *)
   type 'a result = ('a, error) Stdlib.result
   
-  (** Configuration for a JMAP API client *)
+  (** Configuration for a JMAP API client as defined in RFC8620 Section 3.1
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.1>
+  *)
   type config = {
-    api_uri: Uri.t;
-    username: string;
-    authentication_token: string;
+    api_uri: Uri.t;                (** The JMAP API endpoint URI *)
+    username: string;              (** The username for authentication *)
+    authentication_token: string;  (** The token for authentication *)
   }
   
-  (** Make a raw JMAP API request *)
+  (** Make a raw JMAP API request as defined in RFC8620 Section 3.3
+      @param config The API client configuration
+      @param request The JMAP request to send
+      @return A result containing the JMAP response or an error
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.3>
+  *)
   val make_request : 
     config -> 
     Types.request ->
     Types.response result Lwt.t
   
-  (** Fetch a Session object from a JMAP server.
-      Can authenticate with either username/password or API token. *)
+  (** Fetch a Session object from a JMAP server as defined in RFC8620 Section 2
+      Can authenticate with either username/password or API token.
+      @param uri The URI of the JMAP session resource
+      @param username Optional username for authentication
+      @param authentication_token Optional password or token for authentication
+      @param api_token Optional API token for Bearer authentication
+      @return A result containing the session object or an error
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
+  *)
   val get_session :
     Uri.t ->
     ?username:string ->
···
     unit ->
     Types.session result Lwt.t
   
-  (** Upload a binary blob to the server *)
+  (** Upload a binary blob to the server as defined in RFC8620 Section 6.1
+      @param config The API client configuration
+      @param account_id The account ID to upload to
+      @param content_type The MIME type of the blob
+      @param data The blob data as a string
+      @return A result containing the upload response or an error
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.1>
+  *)
   val upload_blob :
     config ->
     account_id:Types.id ->
···
     string ->
     Types.upload_response result Lwt.t
   
-  (** Download a binary blob from the server *)
+  (** Download a binary blob from the server as defined in RFC8620 Section 6.2
+      @param config The API client configuration
+      @param account_id The account ID that contains the blob
+      @param blob_id The ID of the blob to download
+      @param type_ Optional MIME type to require for the blob
+      @param name Optional name for the downloaded blob
+      @return A result containing the blob data as a string or an error
+      @see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.2>
+  *)
   val download_blob :
     config ->
     account_id:Types.id ->
···
     ?name:string ->
     unit ->
     string result Lwt.t
-end
+end

lib/jmap_mail.mli

···
-(** Implementation of the JMAP Mail extension, as defined in RFC8621 *)
+(** Implementation of the JMAP Mail extension, as defined in RFC8621 
+    @see <https://datatracker.ietf.org/doc/html/rfc8621> RFC8621
+    
+    This module implements the JMAP Mail specification, providing types and
+    functions for working with emails, mailboxes, threads, and other mail-related
+    objects in the JMAP protocol.
+*)
 
-(** Module for managing JMAP Mail-specific capability URIs *)
+(** Module for managing JMAP Mail-specific capability URIs as defined in RFC8621 Section 1.3
+    @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3> RFC8621 Section 1.3
+*)
 module Capability : sig
-  (** Mail capability URI *)
+  (** Mail capability URI as defined in RFC8621 Section 1.3
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
+  *)
   val mail_uri : string
 
-  (** Submission capability URI *)
+  (** Submission capability URI as defined in RFC8621 Section 1.3
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
+  *)
   val submission_uri : string
 
-  (** Vacation response capability URI *)
+  (** Vacation response capability URI as defined in RFC8621 Section 1.3
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
+  *)
   val vacation_response_uri : string
 
-  (** All mail extension capability types *)
+  (** All mail extension capability types as defined in RFC8621 Section 1.3
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
+  *)
   type t =
-    | Mail            (** Mail capability *)
-    | Submission      (** Submission capability *)
-    | VacationResponse (** Vacation response capability *)
-    | Extension of string (** Custom extension *)
+    | Mail            (** Mail capability for emails and mailboxes *)
+    | Submission      (** Submission capability for sending emails *)
+    | VacationResponse (** Vacation response capability for auto-replies *)
+    | Extension of string (** Custom extension capabilities *)
 
-  (** Convert capability to URI string *)
+  (** Convert capability to URI string
+      @param capability The capability to convert
+      @return The full URI string for the capability
+  *)
   val to_string : t -> string
 
-  (** Parse a string to a capability *)
+  (** Parse a string to a capability
+      @param uri The capability URI string to parse
+      @return The parsed capability type
+  *)
   val of_string : string -> t
 
-  (** Check if a capability is a standard mail capability *)
+  (** Check if a capability is a standard mail capability
+      @param capability The capability to check
+      @return True if the capability is a standard JMAP Mail capability
+  *)
   val is_standard : t -> bool
 
-  (** Check if a capability string is a standard mail capability *)
+  (** Check if a capability string is a standard mail capability
+      @param uri The capability URI string to check
+      @return True if the string represents a standard JMAP Mail capability
+  *)
   val is_standard_string : string -> bool
 
-  (** Create a list of capability strings *)
+  (** Create a list of capability strings
+      @param capabilities List of capability types
+      @return List of capability URI strings
+  *)
   val strings_of_capabilities : t list -> string list
 end
 
-(** Types for the JMAP Mail extension *)
+(** Types for the JMAP Mail extension as defined in RFC8621
+    @see <https://datatracker.ietf.org/doc/html/rfc8621>
+*)
 module Types : sig
   open Jmap.Types
 
-  (** {1 Mail capabilities} *)
+  (** {1 Mail capabilities}
+      Capability URIs for JMAP Mail extension as defined in RFC8621 Section 1.3
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
+  *)
 
-  (** Capability URI for JMAP Mail*)
+  (** Capability URI for JMAP Mail as defined in RFC8621 Section 1.3
+      Identifies support for the Mail data model
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
+  *)
   val capability_mail : string
 
-  (** Capability URI for JMAP Submission *)
+  (** Capability URI for JMAP Submission as defined in RFC8621 Section 1.3
+      Identifies support for email submission
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
+  *)
   val capability_submission : string
   
-  (** Capability URI for JMAP Vacation Response *)
+  (** Capability URI for JMAP Vacation Response as defined in RFC8621 Section 1.3
+      Identifies support for vacation auto-reply functionality
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-1.3>
+  *)
   val capability_vacation_response : string
 
-  (** {1:mailbox Mailbox objects} *)
+  (** {1:mailbox Mailbox objects}
+      Mailbox types as defined in RFC8621 Section 2
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
+  *)
 
-  (** A role for a mailbox. See RFC8621 Section 2. *)
+  (** A role for a mailbox as defined in RFC8621 Section 2.
+      Standardized roles for special mailboxes like Inbox, Sent, etc.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
+  *)
   type mailbox_role =
-    | All (** All mail *)
-    | Archive (** Archived mail *)
-    | Drafts (** Draft messages *)
-    | Flagged (** Starred/flagged mail *)
-    | Important (** Important mail *)
-    | Inbox (** Inbox *)
-    | Junk (** Spam/Junk mail *)
-    | Sent (** Sent mail *)
-    | Trash (** Deleted/Trash mail *)
-    | Unknown of string (** Server-specific roles *)
+    | All (** All mail mailbox *)
+    | Archive (** Archived mail mailbox *)
+    | Drafts (** Draft messages mailbox *)
+    | Flagged (** Starred/flagged mail mailbox *)
+    | Important (** Important mail mailbox *)
+    | Inbox (** Primary inbox mailbox *)
+    | Junk (** Spam/Junk mail mailbox *)
+    | Sent (** Sent mail mailbox *)
+    | Trash (** Deleted/Trash mail mailbox *)
+    | Unknown of string (** Server-specific custom roles *)
   
-  (** A mailbox (folder) in a mail account. See RFC8621 Section 2. *)
+  (** A mailbox (folder) in a mail account as defined in RFC8621 Section 2.
+      Represents an email folder or label in the account.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
+  *)
   type mailbox = {
-    id : id;
-    name : string;
-    parent_id : id option;
-    role : mailbox_role option;
-    sort_order : unsigned_int;
-    total_emails : unsigned_int;
-    unread_emails : unsigned_int;
-    total_threads : unsigned_int;
-    unread_threads : unsigned_int;
-    is_subscribed : bool;
-    my_rights : mailbox_rights;
+    id : id;  (** Server-assigned ID for the mailbox *)
+    name : string;  (** User-visible name for the mailbox *)
+    parent_id : id option;  (** ID of the parent mailbox, if any *)
+    role : mailbox_role option;  (** The role of this mailbox, if it's a special mailbox *)
+    sort_order : unsigned_int;  (** Position for mailbox in the UI *)
+    total_emails : unsigned_int;  (** Total number of emails in the mailbox *)
+    unread_emails : unsigned_int;  (** Number of unread emails in the mailbox *)
+    total_threads : unsigned_int;  (** Total number of threads in the mailbox *)
+    unread_threads : unsigned_int;  (** Number of threads with unread emails *)
+    is_subscribed : bool;  (** Has the user subscribed to this mailbox *)
+    my_rights : mailbox_rights;  (** Access rights for the user on this mailbox *)
   }
 
-  (** Rights for a mailbox. See RFC8621 Section 2. *)
+  (** Rights for a mailbox as defined in RFC8621 Section 2.
+      Determines the operations a user can perform on a mailbox.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2>
+  *)
   and mailbox_rights = {
-    may_read_items : bool;
-    may_add_items : bool;
-    may_remove_items : bool;
-    may_set_seen : bool;
-    may_set_keywords : bool;
-    may_create_child : bool;
-    may_rename : bool;
-    may_delete : bool;
-    may_submit : bool;
+    may_read_items : bool;  (** Can the user read messages in this mailbox *)
+    may_add_items : bool;  (** Can the user add messages to this mailbox *)
+    may_remove_items : bool;  (** Can the user remove messages from this mailbox *)
+    may_set_seen : bool;  (** Can the user mark messages as read/unread *)
+    may_set_keywords : bool;  (** Can the user set keywords/flags on messages *)
+    may_create_child : bool;  (** Can the user create child mailboxes *)
+    may_rename : bool;  (** Can the user rename this mailbox *)
+    may_delete : bool;  (** Can the user delete this mailbox *)
+    may_submit : bool;  (** Can the user submit messages in this mailbox for delivery *)
   }
 
-  (** Filter condition for mailbox queries. See RFC8621 Section 2.3. *)
+  (** Filter condition for mailbox queries as defined in RFC8621 Section 2.3.
+      Used to filter mailboxes in queries.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
+  *)
   type mailbox_filter_condition = {
-    parent_id : id option;
-    name : string option;
-    role : string option;
-    has_any_role : bool option;
-    is_subscribed : bool option;
+    parent_id : id option;  (** Only include mailboxes with this parent *)
+    name : string option;  (** Only include mailboxes with this name (case-insensitive substring match) *)
+    role : string option;  (** Only include mailboxes with this role *)
+    has_any_role : bool option;  (** If true, only include mailboxes with a role, if false those without *)
+    is_subscribed : bool option;  (** If true, only include subscribed mailboxes, if false unsubscribed *)
   }
 
+  (** Filter for mailbox queries as defined in RFC8621 Section 2.3.
+      Complex filter for Mailbox/query method.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
+  *)
   type mailbox_query_filter = [
-    | `And of mailbox_query_filter list
-    | `Or of mailbox_query_filter list
-    | `Not of mailbox_query_filter
-    | `Condition of mailbox_filter_condition
+    | `And of mailbox_query_filter list  (** Logical AND of filters *)
+    | `Or of mailbox_query_filter list   (** Logical OR of filters *)
+    | `Not of mailbox_query_filter       (** Logical NOT of a filter *)
+    | `Condition of mailbox_filter_condition  (** Simple condition filter *)
   ]
 
-  (** Mailbox/get request arguments. See RFC8621 Section 2.1. *)
+  (** Mailbox/get request arguments as defined in RFC8621 Section 2.1.
+      Used to fetch mailboxes by ID.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.1>
+  *)
   type mailbox_get_arguments = {
-    account_id : id;
-    ids : id list option;
-    properties : string list option;
+    account_id : id;  (** The account to fetch mailboxes from *)
+    ids : id list option;  (** The IDs of mailboxes to fetch, null means all *)
+    properties : string list option;  (** Properties to return, null means all *)
   }
 
-  (** Mailbox/get response. See RFC8621 Section 2.1. *)
+  (** Mailbox/get response as defined in RFC8621 Section 2.1.
+      Contains requested mailboxes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.1>
+  *)
   type mailbox_get_response = {
-    account_id : id;
-    state : string;
-    list : mailbox list;
-    not_found : id list;
+    account_id : id;  (** The account from which mailboxes were fetched *)
+    state : string;  (** A string representing the state on the server *)
+    list : mailbox list;  (** The list of mailboxes requested *)
+    not_found : id list;  (** IDs requested that could not be found *)
   }
 
-  (** Mailbox/changes request arguments. See RFC8621 Section 2.2. *)
+  (** Mailbox/changes request arguments as defined in RFC8621 Section 2.2.
+      Used to get mailbox changes since a previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.2>
+  *)
   type mailbox_changes_arguments = {
-    account_id : id;
-    since_state : string;
-    max_changes : unsigned_int option;
+    account_id : id;  (** The account to get changes for *)
+    since_state : string;  (** The previous state to compare to *)
+    max_changes : unsigned_int option;  (** Maximum number of changes to return *)
   }
 
-  (** Mailbox/changes response. See RFC8621 Section 2.2. *)
+  (** Mailbox/changes response as defined in RFC8621 Section 2.2.
+      Reports mailboxes that have changed since a previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.2>
+  *)
   type mailbox_changes_response = {
-    account_id : id;
-    old_state : string;
-    new_state : string;
-    has_more_changes : bool;
-    created : id list;
-    updated : id list;
-    destroyed : id list;
+    account_id : id;  (** The account changes are for *)
+    old_state : string;  (** The state provided in the request *)
+    new_state : string;  (** The current state on the server *)
+    has_more_changes : bool;  (** If true, more changes are available *)
+    created : id list;  (** IDs of mailboxes created since old_state *)
+    updated : id list;  (** IDs of mailboxes updated since old_state *)
+    destroyed : id list;  (** IDs of mailboxes destroyed since old_state *)
   }
 
-  (** Mailbox/query request arguments. See RFC8621 Section 2.3. *)
+  (** Mailbox/query request arguments as defined in RFC8621 Section 2.3.
+      Used to query mailboxes based on filter criteria.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
+  *)
   type mailbox_query_arguments = {
-    account_id : id;
-    filter : mailbox_query_filter option;
-    sort : [ `name | `role | `sort_order ] list option;
-    limit : unsigned_int option;
+    account_id : id;  (** The account to query *)
+    filter : mailbox_query_filter option;  (** Filter to match mailboxes against *)
+    sort : [ `name | `role | `sort_order ] list option;  (** Sort criteria *)
+    limit : unsigned_int option;  (** Maximum number of results to return *)
   }
 
-  (** Mailbox/query response. See RFC8621 Section 2.3. *)
+  (** Mailbox/query response as defined in RFC8621 Section 2.3.
+      Contains IDs of mailboxes matching the query.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.3>
+  *)
   type mailbox_query_response = {
-    account_id : id;
-    query_state : string;
-    can_calculate_changes : bool;
-    position : unsigned_int;
-    ids : id list;
-    total : unsigned_int option;
+    account_id : id;  (** The account that was queried *)
+    query_state : string;  (** State string for the query results *)
+    can_calculate_changes : bool;  (** Whether queryChanges can be used with these results *)
+    position : unsigned_int;  (** Zero-based index of the first result *)
+    ids : id list;  (** IDs of mailboxes matching the query *)
+    total : unsigned_int option;  (** Total number of matches if requested *)
   }
 
-  (** Mailbox/queryChanges request arguments. See RFC8621 Section 2.4. *)
+  (** Mailbox/queryChanges request arguments as defined in RFC8621 Section 2.4.
+      Used to get changes to mailbox query results.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.4>
+  *)
   type mailbox_query_changes_arguments = {
-    account_id : id;
-    filter : mailbox_query_filter option;
-    sort : [ `name | `role | `sort_order ] list option;
-    since_query_state : string;
-    max_changes : unsigned_int option;
-    up_to_id : id option;
+    account_id : id;  (** The account to query *)
+    filter : mailbox_query_filter option;  (** Same filter as the original query *)
+    sort : [ `name | `role | `sort_order ] list option;  (** Same sort as the original query *)
+    since_query_state : string;  (** The query_state from the previous result *)
+    max_changes : unsigned_int option;  (** Maximum number of changes to return *)
+    up_to_id : id option;  (** ID of the last mailbox to check for changes *)
   }
 
-  (** Mailbox/queryChanges response. See RFC8621 Section 2.4. *)
+  (** Mailbox/queryChanges response as defined in RFC8621 Section 2.4.
+      Reports changes to a mailbox query since the previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.4>
+  *)
   type mailbox_query_changes_response = {
-    account_id : id;
-    old_query_state : string;
-    new_query_state : string;
-    total : unsigned_int option;
-    removed : id list;
-    added : mailbox_query_changes_added list;
+    account_id : id;  (** The account that was queried *)
+    old_query_state : string;  (** The query_state from the request *)
+    new_query_state : string;  (** The current query_state on the server *)
+    total : unsigned_int option;  (** Updated total number of matches, if requested *)
+    removed : id list;  (** IDs that were in the old results but not the new *)
+    added : mailbox_query_changes_added list;  (** IDs that are in the new results but not the old *)
   }
 
+  (** Added item in mailbox query changes as defined in RFC8621 Section 2.4.
+      Represents a mailbox added to query results.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.4>
+  *)
   and mailbox_query_changes_added = {
-    id : id;
-    index : unsigned_int;
+    id : id;  (** ID of the added mailbox *)
+    index : unsigned_int;  (** Zero-based index of the added mailbox in the results *)
   }
 
-  (** Mailbox/set request arguments. See RFC8621 Section 2.5. *)
+  (** Mailbox/set request arguments as defined in RFC8621 Section 2.5.
+      Used to create, update, and destroy mailboxes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
+  *)
   type mailbox_set_arguments = {
-    account_id : id;
-    if_in_state : string option;
-    create : (id * mailbox_creation) list option;
-    update : (id * mailbox_update) list option;
-    destroy : id list option;
+    account_id : id;  (** The account to make changes in *)
+    if_in_state : string option;  (** Only apply changes if in this state *)
+    create : (id * mailbox_creation) list option;  (** Map of creation IDs to mailboxes to create *)
+    update : (id * mailbox_update) list option;  (** Map of IDs to update properties *)
+    destroy : id list option;  (** List of IDs to destroy *)
   }
 
+  (** Properties for mailbox creation as defined in RFC8621 Section 2.5.
+      Used to create new mailboxes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
+  *)
   and mailbox_creation = {
-    name : string;
-    parent_id : id option;
-    role : string option;
-    sort_order : unsigned_int option;
-    is_subscribed : bool option;
+    name : string;  (** Name for the new mailbox *)
+    parent_id : id option;  (** ID of the parent mailbox, if any *)
+    role : string option;  (** Role for the mailbox, if it's a special-purpose mailbox *)
+    sort_order : unsigned_int option;  (** Sort order, defaults to 0 *)
+    is_subscribed : bool option;  (** Whether the mailbox is subscribed, defaults to true *)
   }
 
+  (** Properties for mailbox update as defined in RFC8621 Section 2.5.
+      Used to update existing mailboxes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
+  *)
   and mailbox_update = {
-    name : string option;
-    parent_id : id option;
-    role : string option;
-    sort_order : unsigned_int option;
-    is_subscribed : bool option;
+    name : string option;  (** New name for the mailbox *)
+    parent_id : id option;  (** New parent ID for the mailbox *)
+    role : string option;  (** New role for the mailbox *)
+    sort_order : unsigned_int option;  (** New sort order for the mailbox *)
+    is_subscribed : bool option;  (** New subscription status for the mailbox *)
   }
 
-  (** Mailbox/set response. See RFC8621 Section 2.5. *)
+  (** Mailbox/set response as defined in RFC8621 Section 2.5.
+      Reports the results of mailbox changes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-2.5>
+  *)
   type mailbox_set_response = {
-    account_id : id;
-    old_state : string option;
-    new_state : string;
-    created : (id * mailbox) list option;
-    updated : id list option;
-    destroyed : id list option;
-    not_created : (id * set_error) list option;
-    not_updated : (id * set_error) list option;
-    not_destroyed : (id * set_error) list option;
+    account_id : id;  (** The account that was modified *)
+    old_state : string option;  (** The state before processing, if changed *)
+    new_state : string;  (** The current state on the server *)
+    created : (id * mailbox) list option;  (** Map of creation IDs to created mailboxes *)
+    updated : id list option;  (** List of IDs that were successfully updated *)
+    destroyed : id list option;  (** List of IDs that were successfully destroyed *)
+    not_created : (id * set_error) list option;  (** Map of IDs to errors for failed creates *)
+    not_updated : (id * set_error) list option;  (** Map of IDs to errors for failed updates *)
+    not_destroyed : (id * set_error) list option;  (** Map of IDs to errors for failed destroys *)
   }
 
-  (** {1:thread Thread objects} *)
+  (** {1:thread Thread objects}
+      Thread types as defined in RFC8621 Section 3
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3>
+  *)
 
-  (** A thread in a mail account. See RFC8621 Section 3. *)
+  (** A thread in a mail account as defined in RFC8621 Section 3.
+      Represents a group of related email messages.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3>
+  *)
   type thread = {
-    id : id;
-    email_ids : id list;
+    id : id;  (** Server-assigned ID for the thread *)
+    email_ids : id list;  (** IDs of emails in the thread *)
   }
 
-  (** Thread/get request arguments. See RFC8621 Section 3.1. *)
+  (** Thread/get request arguments as defined in RFC8621 Section 3.1.
+      Used to fetch threads by ID.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.1>
+  *)
   type thread_get_arguments = {
-    account_id : id;
-    ids : id list option;
-    properties : string list option;
+    account_id : id;  (** The account to fetch threads from *)
+    ids : id list option;  (** The IDs of threads to fetch, null means all *)
+    properties : string list option;  (** Properties to return, null means all *)
   }
 
-  (** Thread/get response. See RFC8621 Section 3.1. *)
+  (** Thread/get response as defined in RFC8621 Section 3.1.
+      Contains requested threads.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.1>
+  *)
   type thread_get_response = {
-    account_id : id;
-    state : string;
-    list : thread list;
-    not_found : id list;
+    account_id : id;  (** The account from which threads were fetched *)
+    state : string;  (** A string representing the state on the server *)
+    list : thread list;  (** The list of threads requested *)
+    not_found : id list;  (** IDs requested that could not be found *)
   }
 
-  (** Thread/changes request arguments. See RFC8621 Section 3.2. *)
+  (** Thread/changes request arguments as defined in RFC8621 Section 3.2.
+      Used to get thread changes since a previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.2>
+  *)
   type thread_changes_arguments = {
-    account_id : id;
-    since_state : string;
-    max_changes : unsigned_int option;
+    account_id : id;  (** The account to get changes for *)
+    since_state : string;  (** The previous state to compare to *)
+    max_changes : unsigned_int option;  (** Maximum number of changes to return *)
   }
 
-  (** Thread/changes response. See RFC8621 Section 3.2. *)
+  (** Thread/changes response as defined in RFC8621 Section 3.2.
+      Reports threads that have changed since a previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-3.2>
+  *)
   type thread_changes_response = {
-    account_id : id;
-    old_state : string;
-    new_state : string;
-    has_more_changes : bool;
-    created : id list;
-    updated : id list;
-    destroyed : id list;
+    account_id : id;  (** The account changes are for *)
+    old_state : string;  (** The state provided in the request *)
+    new_state : string;  (** The current state on the server *)
+    has_more_changes : bool;  (** If true, more changes are available *)
+    created : id list;  (** IDs of threads created since old_state *)
+    updated : id list;  (** IDs of threads updated since old_state *)
+    destroyed : id list;  (** IDs of threads destroyed since old_state *)
   }
 
-  (** {1:email Email objects} *)
+  (** {1:email Email objects}
+      Email types as defined in RFC8621 Section 4
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4>
+  *)
 
-  (** Addressing (mailbox) information. See RFC8621 Section 4.1.1. *)
+  (** Addressing (mailbox) information as defined in RFC8621 Section 4.1.1.
+      Represents an email address with optional display name.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.1.1>
+  *)
   type email_address = {
-    name : string option;
-    email : string;
-    parameters : (string * string) list;
+    name : string option;  (** Display name of the mailbox (e.g., "John Doe") *)
+    email : string;  (** The email address (e.g., "[e-mail]") *)
+    parameters : (string * string) list;  (** Additional parameters for the address *)
   }
 
-  (** Message header field. See RFC8621 Section 4.1.2. *)
+  (** Message header field as defined in RFC8621 Section 4.1.2.
+      Represents an email header.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.1.2>
+  *)
   type header = {
-    name : string;
-    value : string;
+    name : string;  (** Name of the header field (e.g., "Subject") *)
+    value : string;  (** Value of the header field *)
   }
 
-  (** Email keyword (flag). See RFC8621 Section 4.3. *)
+  (** Email keyword (flag) as defined in RFC8621 Section 4.3.
+      Represents a flag or tag on an email message.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.3>
+  *)
   type keyword =
-    | Flagged
-    | Answered
-    | Draft
-    | Forwarded
-    | Phishing
-    | Junk
-    | NotJunk
-    | Seen
-    | Unread
-    | Custom of string
+    | Flagged    (** Message is flagged/starred *)
+    | Answered   (** Message has been replied to *)
+    | Draft      (** Message is a draft *)
+    | Forwarded  (** Message has been forwarded *)
+    | Phishing   (** Message has been reported as phishing *)
+    | Junk       (** Message is spam/junk *)
+    | NotJunk    (** Message is explicitly not spam *)
+    | Seen       (** Message has been read *)
+    | Unread     (** Message is unread (inverse of $seen) *)
+    | Custom of string  (** Custom/non-standard keywords *)
   
-  (** Email message. See RFC8621 Section 4. *)
+  (** Email message as defined in RFC8621 Section 4.
+      Represents an email message in a mail account.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4>
+  *)
   type email = {
-    id : id;
-    blob_id : id;
-    thread_id : id;
-    mailbox_ids : (id * bool) list;
-    keywords : (keyword * bool) list;
-    size : unsigned_int;
-    received_at : utc_date;
-    message_id : string list;
-    in_reply_to : string list option;
-    references : string list option;
-    sender : email_address list option;
-    from : email_address list option;
-    to_ : email_address list option;
-    cc : email_address list option;
-    bcc : email_address list option;
-    reply_to : email_address list option;
-    subject : string option;
-    sent_at : utc_date option;
-    has_attachment : bool option;
-    preview : string option;
-    body_values : (string * string) list option;
-    text_body : email_body_part list option;
-    html_body : email_body_part list option;
-    attachments : email_body_part list option;
-    headers : header list option;
+    id : id;  (** Server-assigned ID for the message *)
+    blob_id : id;  (** ID of the raw message content blob *)
+    thread_id : id;  (** ID of the thread this message belongs to *)
+    mailbox_ids : (id * bool) list;  (** Map of mailbox IDs to boolean (whether message belongs to mailbox) *)
+    keywords : (keyword * bool) list;  (** Map of keywords to boolean (whether message has keyword) *)
+    size : unsigned_int;  (** Size of the message in octets *)
+    received_at : utc_date;  (** When the message was received by the server *)
+    message_id : string list;  (** Message-ID header values *)
+    in_reply_to : string list option;  (** In-Reply-To header values *)
+    references : string list option;  (** References header values *)
+    sender : email_address list option;  (** Sender header addresses *)
+    from : email_address list option;  (** From header addresses *)
+    to_ : email_address list option;  (** To header addresses *)
+    cc : email_address list option;  (** Cc header addresses *)
+    bcc : email_address list option;  (** Bcc header addresses *)
+    reply_to : email_address list option;  (** Reply-To header addresses *)
+    subject : string option;  (** Subject header value *)
+    sent_at : utc_date option;  (** Date header value as a date-time *)
+    has_attachment : bool option;  (** Does the message have any attachments *)
+    preview : string option;  (** Preview of the message (first bit of text) *)
+    body_values : (string * string) list option;  (** Map of part IDs to text content *)
+    text_body : email_body_part list option;  (** Plain text message body parts *)
+    html_body : email_body_part list option;  (** HTML message body parts *)
+    attachments : email_body_part list option;  (** Attachment parts in the message *)
+    headers : header list option;  (** All headers in the message *)
   }
 
-  (** Email body part. See RFC8621 Section 4.1.4. *)
+  (** Email body part as defined in RFC8621 Section 4.1.4.
+      Represents a MIME part in an email message.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.1.4>
+  *)
   and email_body_part = {
-    part_id : string option;
-    blob_id : id option;
-    size : unsigned_int option;
-    headers : header list option;
-    name : string option;
-    type_ : string option;
-    charset : string option;
-    disposition : string option;
-    cid : string option;
-    language : string list option;
-    location : string option;
-    sub_parts : email_body_part list option;
-    header_parameter_name : string option;
-    header_parameter_value : string option;
+    part_id : string option;  (** Server-assigned ID for the MIME part *)
+    blob_id : id option;  (** ID of the raw content for this part *)
+    size : unsigned_int option;  (** Size of the part in octets *)
+    headers : header list option;  (** Headers for this MIME part *)
+    name : string option;  (** Filename of this part, if any *)
+    type_ : string option;  (** MIME type of the part *)
+    charset : string option;  (** Character set of the part, if applicable *)
+    disposition : string option;  (** Content-Disposition value *)
+    cid : string option;  (** Content-ID value *)
+    language : string list option;  (** Content-Language values *)
+    location : string option;  (** Content-Location value *)
+    sub_parts : email_body_part list option;  (** Child MIME parts for multipart types *)
+    header_parameter_name : string option;  (** Header parameter name (for headers with parameters) *)
+    header_parameter_value : string option;  (** Header parameter value (for headers with parameters) *)
   }
   
-  (** Email query filter condition. See RFC8621 Section 4.4. *)
+  (** Email query filter condition as defined in RFC8621 Section 4.4.
+      Specifies conditions for filtering emails in queries.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
+  *)
   type email_filter_condition = {
-    in_mailbox : id option;
-    in_mailbox_other_than : id list option;
-    min_size : unsigned_int option;
-    max_size : unsigned_int option;
-    before : utc_date option;
-    after : utc_date option;
-    header : (string * string) option;
-    from : string option;
-    to_ : string option;
-    cc : string option;
-    bcc : string option;
-    subject : string option;
-    body : string option;
-    has_keyword : string option;
-    not_keyword : string option;
-    has_attachment : bool option;
-    text : string option;
+    in_mailbox : id option;  (** Only include emails in this mailbox *)
+    in_mailbox_other_than : id list option;  (** Only include emails not in these mailboxes *)
+    min_size : unsigned_int option;  (** Only include emails of at least this size in octets *)
+    max_size : unsigned_int option;  (** Only include emails of at most this size in octets *)
+    before : utc_date option;  (** Only include emails received before this date-time *)
+    after : utc_date option;  (** Only include emails received after this date-time *)
+    header : (string * string) option;  (** Only include emails with header matching value (name, value) *)
+    from : string option;  (** Only include emails with From containing this text *)
+    to_ : string option;  (** Only include emails with To containing this text *)
+    cc : string option;  (** Only include emails with CC containing this text *)
+    bcc : string option;  (** Only include emails with BCC containing this text *)
+    subject : string option;  (** Only include emails with Subject containing this text *)
+    body : string option;  (** Only include emails with body containing this text *)
+    has_keyword : string option;  (** Only include emails with this keyword *)
+    not_keyword : string option;  (** Only include emails without this keyword *)
+    has_attachment : bool option;  (** If true, only include emails with attachments *)
+    text : string option;  (** Only include emails with this text in headers or body *)
   }
 
+  (** Filter for email queries as defined in RFC8621 Section 4.4.
+      Complex filter for Email/query method.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
+  *)
   type email_query_filter = [
-    | `And of email_query_filter list
-    | `Or of email_query_filter list
-    | `Not of email_query_filter
-    | `Condition of email_filter_condition
+    | `And of email_query_filter list  (** Logical AND of filters *)
+    | `Or of email_query_filter list   (** Logical OR of filters *)
+    | `Not of email_query_filter       (** Logical NOT of a filter *)
+    | `Condition of email_filter_condition  (** Simple condition filter *)
   ]
 
-  (** Email/get request arguments. See RFC8621 Section 4.5. *)
+  (** Email/get request arguments as defined in RFC8621 Section 4.5.
+      Used to fetch emails by ID.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.5>
+  *)
   type email_get_arguments = {
-    account_id : id;
-    ids : id list option;
-    properties : string list option;
-    body_properties : string list option;
-    fetch_text_body_values : bool option;
-    fetch_html_body_values : bool option;
-    fetch_all_body_values : bool option;
-    max_body_value_bytes : unsigned_int option;
+    account_id : id;  (** The account to fetch emails from *)
+    ids : id list option;  (** The IDs of emails to fetch, null means all *)
+    properties : string list option;  (** Properties to return, null means all *)
+    body_properties : string list option;  (** Properties to return on body parts *)
+    fetch_text_body_values : bool option;  (** Whether to fetch text body content *)
+    fetch_html_body_values : bool option;  (** Whether to fetch HTML body content *)
+    fetch_all_body_values : bool option;  (** Whether to fetch all body content *)
+    max_body_value_bytes : unsigned_int option;  (** Maximum size of body values to return *)
   }
 
-  (** Email/get response. See RFC8621 Section 4.5. *)
+  (** Email/get response as defined in RFC8621 Section 4.5.
+      Contains requested emails.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.5>
+  *)
   type email_get_response = {
-    account_id : id;
-    state : string;
-    list : email list;
-    not_found : id list;
+    account_id : id;  (** The account from which emails were fetched *)
+    state : string;  (** A string representing the state on the server *)
+    list : email list;  (** The list of emails requested *)
+    not_found : id list;  (** IDs requested that could not be found *)
   }
 
-  (** Email/changes request arguments. See RFC8621 Section 4.6. *)
+  (** Email/changes request arguments as defined in RFC8621 Section 4.6.
+      Used to get email changes since a previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.6>
+  *)
   type email_changes_arguments = {
-    account_id : id;
-    since_state : string;
-    max_changes : unsigned_int option;
+    account_id : id;  (** The account to get changes for *)
+    since_state : string;  (** The previous state to compare to *)
+    max_changes : unsigned_int option;  (** Maximum number of changes to return *)
   }
 
-  (** Email/changes response. See RFC8621 Section 4.6. *)
+  (** Email/changes response as defined in RFC8621 Section 4.6.
+      Reports emails that have changed since a previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.6>
+  *)
   type email_changes_response = {
-    account_id : id;
-    old_state : string;
-    new_state : string;
-    has_more_changes : bool;
-    created : id list;
-    updated : id list;
-    destroyed : id list;
+    account_id : id;  (** The account changes are for *)
+    old_state : string;  (** The state provided in the request *)
+    new_state : string;  (** The current state on the server *)
+    has_more_changes : bool;  (** If true, more changes are available *)
+    created : id list;  (** IDs of emails created since old_state *)
+    updated : id list;  (** IDs of emails updated since old_state *)
+    destroyed : id list;  (** IDs of emails destroyed since old_state *)
   }
 
-  (** Email/query request arguments. See RFC8621 Section 4.4. *)
+  (** Email/query request arguments as defined in RFC8621 Section 4.4.
+      Used to query emails based on filter criteria.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
+  *)
   type email_query_arguments = {
-    account_id : id;
-    filter : email_query_filter option;
-    sort : comparator list option;
-    collapse_threads : bool option;
-    position : unsigned_int option;
-    anchor : id option;
-    anchor_offset : int_t option;
-    limit : unsigned_int option;
-    calculate_total : bool option;
+    account_id : id;  (** The account to query *)
+    filter : email_query_filter option;  (** Filter to match emails against *)
+    sort : comparator list option;  (** Sort criteria *)
+    collapse_threads : bool option;  (** Whether to collapse threads in the results *)
+    position : unsigned_int option;  (** Zero-based index of first result to return *)
+    anchor : id option;  (** ID of email to use as reference point *)
+    anchor_offset : int_t option;  (** Offset from anchor to start returning results *)
+    limit : unsigned_int option;  (** Maximum number of results to return *)
+    calculate_total : bool option;  (** Whether to calculate the total number of matching emails *)
   }
 
-  (** Email/query response. See RFC8621 Section 4.4. *)
+  (** Email/query response as defined in RFC8621 Section 4.4.
+      Contains IDs of emails matching the query.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.4>
+  *)
   type email_query_response = {
-    account_id : id;
-    query_state : string;
-    can_calculate_changes : bool;
-    position : unsigned_int;
-    ids : id list;
-    total : unsigned_int option;
-    thread_ids : id list option;
+    account_id : id;  (** The account that was queried *)
+    query_state : string;  (** State string for the query results *)
+    can_calculate_changes : bool;  (** Whether queryChanges can be used with these results *)
+    position : unsigned_int;  (** Zero-based index of the first result *)
+    ids : id list;  (** IDs of emails matching the query *)
+    total : unsigned_int option;  (** Total number of matches if requested *)
+    thread_ids : id list option;  (** IDs of threads if collapse_threads was true *)
   }
 
-  (** Email/queryChanges request arguments. See RFC8621 Section 4.7. *)
+  (** Email/queryChanges request arguments as defined in RFC8621 Section 4.7.
+      Used to get changes to email query results.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.7>
+  *)
   type email_query_changes_arguments = {
-    account_id : id;
-    filter : email_query_filter option;
-    sort : comparator list option;
-    collapse_threads : bool option;
-    since_query_state : string;
-    max_changes : unsigned_int option;
-    up_to_id : id option;
+    account_id : id;  (** The account to query *)
+    filter : email_query_filter option;  (** Same filter as the original query *)
+    sort : comparator list option;  (** Same sort as the original query *)
+    collapse_threads : bool option;  (** Same collapse_threads as the original query *)
+    since_query_state : string;  (** The query_state from the previous result *)
+    max_changes : unsigned_int option;  (** Maximum number of changes to return *)
+    up_to_id : id option;  (** ID of the last email to check for changes *)
   }
 
-  (** Email/queryChanges response. See RFC8621 Section 4.7. *)
+  (** Email/queryChanges response as defined in RFC8621 Section 4.7.
+      Reports changes to an email query since the previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.7>
+  *)
   type email_query_changes_response = {
-    account_id : id;
-    old_query_state : string;
-    new_query_state : string;
-    total : unsigned_int option;
-    removed : id list;
-    added : email_query_changes_added list;
+    account_id : id;  (** The account that was queried *)
+    old_query_state : string;  (** The query_state from the request *)
+    new_query_state : string;  (** The current query_state on the server *)
+    total : unsigned_int option;  (** Updated total number of matches, if requested *)
+    removed : id list;  (** IDs that were in the old results but not the new *)
+    added : email_query_changes_added list;  (** IDs that are in the new results but not the old *)
   }
 
+  (** Added item in email query changes as defined in RFC8621 Section 4.7.
+      Represents an email added to query results.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.7>
+  *)
   and email_query_changes_added = {
-    id : id;
-    index : unsigned_int;
+    id : id;  (** ID of the added email *)
+    index : unsigned_int;  (** Zero-based index of the added email in the results *)
   }
 
-  (** Email/set request arguments. See RFC8621 Section 4.8. *)
+  (** Email/set request arguments as defined in RFC8621 Section 4.8.
+      Used to create, update, and destroy emails.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
+  *)
   type email_set_arguments = {
-    account_id : id;
-    if_in_state : string option;
-    create : (id * email_creation) list option;
-    update : (id * email_update) list option;
-    destroy : id list option;
+    account_id : id;  (** The account to make changes in *)
+    if_in_state : string option;  (** Only apply changes if in this state *)
+    create : (id * email_creation) list option;  (** Map of creation IDs to emails to create *)
+    update : (id * email_update) list option;  (** Map of IDs to update properties *)
+    destroy : id list option;  (** List of IDs to destroy *)
   }
 
+  (** Properties for email creation as defined in RFC8621 Section 4.8.
+      Used to create new emails.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
+  *)
   and email_creation = {
-    mailbox_ids : (id * bool) list;
-    keywords : (keyword * bool) list option;
-    received_at : utc_date option;
-    message_id : string list option;
-    in_reply_to : string list option;
-    references : string list option;
-    sender : email_address list option;
-    from : email_address list option;
-    to_ : email_address list option;
-    cc : email_address list option;
-    bcc : email_address list option;
-    reply_to : email_address list option;
-    subject : string option;
-    body_values : (string * string) list option;
-    text_body : email_body_part list option;
-    html_body : email_body_part list option;
-    attachments : email_body_part list option;
-    headers : header list option;
+    mailbox_ids : (id * bool) list;  (** Map of mailbox IDs to boolean (whether message belongs to mailbox) *)
+    keywords : (keyword * bool) list option;  (** Map of keywords to boolean (whether message has keyword) *)
+    received_at : utc_date option;  (** When the message was received by the server *)
+    message_id : string list option;  (** Message-ID header values *)
+    in_reply_to : string list option;  (** In-Reply-To header values *)
+    references : string list option;  (** References header values *)
+    sender : email_address list option;  (** Sender header addresses *)
+    from : email_address list option;  (** From header addresses *)
+    to_ : email_address list option;  (** To header addresses *)
+    cc : email_address list option;  (** Cc header addresses *)
+    bcc : email_address list option;  (** Bcc header addresses *)
+    reply_to : email_address list option;  (** Reply-To header addresses *)
+    subject : string option;  (** Subject header value *)
+    body_values : (string * string) list option;  (** Map of part IDs to text content *)
+    text_body : email_body_part list option;  (** Plain text message body parts *)
+    html_body : email_body_part list option;  (** HTML message body parts *)
+    attachments : email_body_part list option;  (** Attachment parts in the message *)
+    headers : header list option;  (** All headers in the message *)
   }
 
+  (** Properties for email update as defined in RFC8621 Section 4.8.
+      Used to update existing emails.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
+  *)
   and email_update = {
-    keywords : (keyword * bool) list option;
-    mailbox_ids : (id * bool) list option;
+    keywords : (keyword * bool) list option;  (** New keywords to set on the email *)
+    mailbox_ids : (id * bool) list option;  (** New mailboxes to set for the email *)
   }
 
-  (** Email/set response. See RFC8621 Section 4.8. *)
+  (** Email/set response as defined in RFC8621 Section 4.8.
+      Reports the results of email changes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.8>
+  *)
   type email_set_response = {
-    account_id : id;
-    old_state : string option;
-    new_state : string;
-    created : (id * email) list option;
-    updated : id list option;
-    destroyed : id list option;
-    not_created : (id * set_error) list option;
-    not_updated : (id * set_error) list option;
-    not_destroyed : (id * set_error) list option;
+    account_id : id;  (** The account that was modified *)
+    old_state : string option;  (** The state before processing, if changed *)
+    new_state : string;  (** The current state on the server *)
+    created : (id * email) list option;  (** Map of creation IDs to created emails *)
+    updated : id list option;  (** List of IDs that were successfully updated *)
+    destroyed : id list option;  (** List of IDs that were successfully destroyed *)
+    not_created : (id * set_error) list option;  (** Map of IDs to errors for failed creates *)
+    not_updated : (id * set_error) list option;  (** Map of IDs to errors for failed updates *)
+    not_destroyed : (id * set_error) list option;  (** Map of IDs to errors for failed destroys *)
   }
 
-  (** Email/copy request arguments. See RFC8621 Section 4.9. *)
+  (** Email/copy request arguments as defined in RFC8621 Section 4.9.
+      Used to copy emails between accounts.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.9>
+  *)
   type email_copy_arguments = {
-    from_account_id : id;
-    account_id : id;
-    create : (id * email_creation) list;
-    on_success_destroy_original : bool option;
+    from_account_id : id;  (** The account to copy emails from *)
+    account_id : id;  (** The account to copy emails to *)
+    create : (id * email_creation) list;  (** Map of creation IDs to email creation properties *)
+    on_success_destroy_original : bool option;  (** Whether to destroy originals after copying *)
   }
 
-  (** Email/copy response. See RFC8621 Section 4.9. *)
+  (** Email/copy response as defined in RFC8621 Section 4.9.
+      Reports the results of copying emails.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.9>
+  *)
   type email_copy_response = {
-    from_account_id : id;
-    account_id : id;
-    created : (id * email) list option;
-    not_created : (id * set_error) list option;
+    from_account_id : id;  (** The account emails were copied from *)
+    account_id : id;  (** The account emails were copied to *)
+    created : (id * email) list option;  (** Map of creation IDs to created emails *)
+    not_created : (id * set_error) list option;  (** Map of IDs to errors for failed copies *)
   }
 
-  (** Email/import request arguments. See RFC8621 Section 4.10. *)
+  (** Email/import request arguments as defined in RFC8621 Section 4.10.
+      Used to import raw emails from blobs.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.10>
+  *)
   type email_import_arguments = {
-    account_id : id;
-    emails : (id * email_import) list;
+    account_id : id;  (** The account to import emails into *)
+    emails : (id * email_import) list;  (** Map of creation IDs to import properties *)
   }
 
+  (** Properties for email import as defined in RFC8621 Section 4.10.
+      Used to import raw emails from blobs.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.10>
+  *)
   and email_import = {
-    blob_id : id;
-    mailbox_ids : (id * bool) list;
-    keywords : (keyword * bool) list option;
-    received_at : utc_date option;
+    blob_id : id;  (** ID of the blob containing the raw message *)
+    mailbox_ids : (id * bool) list;  (** Map of mailbox IDs to boolean (whether message belongs to mailbox) *)
+    keywords : (keyword * bool) list option;  (** Map of keywords to boolean (whether message has keyword) *)
+    received_at : utc_date option;  (** When the message was received, defaults to now *)
   }
 
-  (** Email/import response. See RFC8621 Section 4.10. *)
+  (** Email/import response as defined in RFC8621 Section 4.10.
+      Reports the results of importing emails.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.10>
+  *)
   type email_import_response = {
-    account_id : id;
-    created : (id * email) list option;
-    not_created : (id * set_error) list option;
+    account_id : id;  (** The account emails were imported into *)
+    created : (id * email) list option;  (** Map of creation IDs to created emails *)
+    not_created : (id * set_error) list option;  (** Map of IDs to errors for failed imports *)
   }
 
-  (** {1:search_snippet Search snippets} *)
+  (** {1:search_snippet Search snippets}
+      Search snippet types as defined in RFC8621 Section 4.11
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
+  *)
 
-  (** SearchSnippet/get request arguments. See RFC8621 Section 4.11. *)
+  (** SearchSnippet/get request arguments as defined in RFC8621 Section 4.11.
+      Used to get highlighted snippets from emails matching a search.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
+  *)
   type search_snippet_get_arguments = {
-    account_id : id;
-    email_ids : id list;
-    filter : email_filter_condition;
+    account_id : id;  (** The account to search in *)
+    email_ids : id list;  (** The IDs of emails to get snippets for *)
+    filter : email_filter_condition;  (** Filter containing the text to find and highlight *)
   }
 
-  (** SearchSnippet/get response. See RFC8621 Section 4.11. *)
+  (** SearchSnippet/get response as defined in RFC8621 Section 4.11.
+      Contains search result snippets with highlighted text.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
+  *)
   type search_snippet_get_response = {
-    account_id : id;
-    list : (id * search_snippet) list;
-    not_found : id list;
+    account_id : id;  (** The account that was searched *)
+    list : (id * search_snippet) list;  (** Map of email IDs to their search snippets *)
+    not_found : id list;  (** IDs for which no snippet could be generated *)
   }
 
+  (** Search snippet for an email as defined in RFC8621 Section 4.11.
+      Contains highlighted parts of emails matching a search.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-4.11>
+  *)
   and search_snippet = {
-    subject : string option;
-    preview : string option;
+    subject : string option;  (** Subject with search terms highlighted *)
+    preview : string option;  (** Email body preview with search terms highlighted *)
   }
 
-  (** {1:submission EmailSubmission objects} *)
+  (** {1:submission EmailSubmission objects}
+      Email submission types as defined in RFC8621 Section 5
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5>
+  *)
 
-  (** EmailSubmission address. See RFC8621 Section 5.1. *)
+  (** EmailSubmission address as defined in RFC8621 Section 5.1.
+      Represents an email address for mail submission.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
+  *)
   type submission_address = {
-    email : string;
-    parameters : (string * string) list option;
+    email : string;  (** The email address (e.g., "[e-mail]") *)
+    parameters : (string * string) list option;  (** SMTP extension parameters *)
   }
 
-  (** Email submission object. See RFC8621 Section 5.1. *)
+  (** Email submission object as defined in RFC8621 Section 5.1.
+      Represents an email that has been or will be sent.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
+  *)
   type email_submission = {
-    id : id;
-    identity_id : id;
-    email_id : id;
-    thread_id : id;
-    envelope : envelope option;
-    send_at : utc_date option;
+    id : id;  (** Server-assigned ID for the submission *)
+    identity_id : id;  (** ID of the identity used to send the email *)
+    email_id : id;  (** ID of the email to send *)
+    thread_id : id;  (** ID of the thread containing the message *)
+    envelope : envelope option;  (** SMTP envelope for the message *)
+    send_at : utc_date option;  (** When to send the email, null for immediate *)
     undo_status : [
-      | `pending
-      | `final
-      | `canceled
-    ] option;
-    delivery_status : (string * submission_status) list option;
-    dsn_blob_ids : (string * id) list option;
-    mdn_blob_ids : (string * id) list option;
+      | `pending  (** Submission can still be canceled *)
+      | `final    (** Submission can no longer be canceled *)
+      | `canceled (** Submission was canceled *)
+    ] option;  (** Current undo status of the submission *)
+    delivery_status : (string * submission_status) list option;  (** Map of recipient to delivery status *)
+    dsn_blob_ids : (string * id) list option;  (** Map of recipient to DSN blob ID *)
+    mdn_blob_ids : (string * id) list option;  (** Map of recipient to MDN blob ID *)
   }
 
-  (** Envelope for mail submission. See RFC8621 Section 5.1. *)
+  (** Envelope for mail submission as defined in RFC8621 Section 5.1.
+      Represents the SMTP envelope for a message.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
+  *)
   and envelope = {
-    mail_from : submission_address;
-    rcpt_to : submission_address list;
+    mail_from : submission_address;  (** Return path for the message *)
+    rcpt_to : submission_address list;  (** Recipients for the message *)
   }
 
-  (** Delivery status for submitted email. See RFC8621 Section 5.1. *)
+  (** Delivery status for submitted email as defined in RFC8621 Section 5.1.
+      Represents the SMTP status of a delivery attempt.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.1>
+  *)
   and submission_status = {
-    smtp_reply : string;
-    delivered : string option;
+    smtp_reply : string;  (** SMTP response from the server *)
+    delivered : string option;  (** Timestamp when message was delivered, if successful *)
   }
 
-  (** EmailSubmission/get request arguments. See RFC8621 Section 5.3. *)
+  (** EmailSubmission/get request arguments as defined in RFC8621 Section 5.3.
+      Used to fetch email submissions by ID.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.3>
+  *)
   type email_submission_get_arguments = {
-    account_id : id;
-    ids : id list option;
-    properties : string list option;
+    account_id : id;  (** The account to fetch submissions from *)
+    ids : id list option;  (** The IDs of submissions to fetch, null means all *)
+    properties : string list option;  (** Properties to return, null means all *)
   }
 
-  (** EmailSubmission/get response. See RFC8621 Section 5.3. *)
+  (** EmailSubmission/get response as defined in RFC8621 Section 5.3.
+      Contains requested email submissions.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.3>
+  *)
   type email_submission_get_response = {
-    account_id : id;
-    state : string;
-    list : email_submission list;
-    not_found : id list;
+    account_id : id;  (** The account from which submissions were fetched *)
+    state : string;  (** A string representing the state on the server *)
+    list : email_submission list;  (** The list of submissions requested *)
+    not_found : id list;  (** IDs requested that could not be found *)
   }
 
-  (** EmailSubmission/changes request arguments. See RFC8621 Section 5.4. *)
+  (** EmailSubmission/changes request arguments as defined in RFC8621 Section 5.4.
+      Used to get submission changes since a previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.4>
+  *)
   type email_submission_changes_arguments = {
-    account_id : id;
-    since_state : string;
-    max_changes : unsigned_int option;
+    account_id : id;  (** The account to get changes for *)
+    since_state : string;  (** The previous state to compare to *)
+    max_changes : unsigned_int option;  (** Maximum number of changes to return *)
   }
 
-  (** EmailSubmission/changes response. See RFC8621 Section 5.4. *)
+  (** EmailSubmission/changes response as defined in RFC8621 Section 5.4.
+      Reports submissions that have changed since a previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.4>
+  *)
   type email_submission_changes_response = {
-    account_id : id;
-    old_state : string;
-    new_state : string;
-    has_more_changes : bool;
-    created : id list;
-    updated : id list;
-    destroyed : id list;
+    account_id : id;  (** The account changes are for *)
+    old_state : string;  (** The state provided in the request *)
+    new_state : string;  (** The current state on the server *)
+    has_more_changes : bool;  (** If true, more changes are available *)
+    created : id list;  (** IDs of submissions created since old_state *)
+    updated : id list;  (** IDs of submissions updated since old_state *)
+    destroyed : id list;  (** IDs of submissions destroyed since old_state *)
   }
 
-  (** EmailSubmission/query filter condition. See RFC8621 Section 5.5. *)
+  (** EmailSubmission/query filter condition as defined in RFC8621 Section 5.5.
+      Specifies conditions for filtering email submissions in queries.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
+  *)
   type email_submission_filter_condition = {
-    identity_id : id option;
-    email_id : id option;
-    thread_id : id option;
-    before : utc_date option;
-    after : utc_date option;
-    subject : string option;
+    identity_id : id option;  (** Only include submissions with this identity *)
+    email_id : id option;  (** Only include submissions for this email *)
+    thread_id : id option;  (** Only include submissions for emails in this thread *)
+    before : utc_date option;  (** Only include submissions created before this date-time *)
+    after : utc_date option;  (** Only include submissions created after this date-time *)
+    subject : string option;  (** Only include submissions with matching subjects *)
   }
 
+  (** Filter for email submission queries as defined in RFC8621 Section 5.5.
+      Complex filter for EmailSubmission/query method.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
+  *)
   type email_submission_query_filter = [
-    | `And of email_submission_query_filter list
-    | `Or of email_submission_query_filter list
-    | `Not of email_submission_query_filter
-    | `Condition of email_submission_filter_condition
+    | `And of email_submission_query_filter list  (** Logical AND of filters *)
+    | `Or of email_submission_query_filter list   (** Logical OR of filters *)
+    | `Not of email_submission_query_filter       (** Logical NOT of a filter *)
+    | `Condition of email_submission_filter_condition  (** Simple condition filter *)
   ]
 
-  (** EmailSubmission/query request arguments. See RFC8621 Section 5.5. *)
+  (** EmailSubmission/query request arguments as defined in RFC8621 Section 5.5.
+      Used to query email submissions based on filter criteria.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
+  *)
   type email_submission_query_arguments = {
-    account_id : id;
-    filter : email_submission_query_filter option;
-    sort : comparator list option;
-    position : unsigned_int option;
-    anchor : id option;
-    anchor_offset : int_t option;
-    limit : unsigned_int option;
-    calculate_total : bool option;
+    account_id : id;  (** The account to query *)
+    filter : email_submission_query_filter option;  (** Filter to match submissions against *)
+    sort : comparator list option;  (** Sort criteria *)
+    position : unsigned_int option;  (** Zero-based index of first result to return *)
+    anchor : id option;  (** ID of submission to use as reference point *)
+    anchor_offset : int_t option;  (** Offset from anchor to start returning results *)
+    limit : unsigned_int option;  (** Maximum number of results to return *)
+    calculate_total : bool option;  (** Whether to calculate the total number of matching submissions *)
   }
 
-  (** EmailSubmission/query response. See RFC8621 Section 5.5. *)
+  (** EmailSubmission/query response as defined in RFC8621 Section 5.5.
+      Contains IDs of email submissions matching the query.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.5>
+  *)
   type email_submission_query_response = {
-    account_id : id;
-    query_state : string;
-    can_calculate_changes : bool;
-    position : unsigned_int;
-    ids : id list;
-    total : unsigned_int option;
+    account_id : id;  (** The account that was queried *)
+    query_state : string;  (** State string for the query results *)
+    can_calculate_changes : bool;  (** Whether queryChanges can be used with these results *)
+    position : unsigned_int;  (** Zero-based index of the first result *)
+    ids : id list;  (** IDs of email submissions matching the query *)
+    total : unsigned_int option;  (** Total number of matches if requested *)
   }
 
-  (** EmailSubmission/set request arguments. See RFC8621 Section 5.6. *)
+  (** EmailSubmission/set request arguments as defined in RFC8621 Section 5.6.
+      Used to create, update, and destroy email submissions.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
+  *)
   type email_submission_set_arguments = {
-    account_id : id;
-    if_in_state : string option;
-    create : (id * email_submission_creation) list option;
-    update : (id * email_submission_update) list option;
-    destroy : id list option;
-    on_success_update_email : (id * email_update) list option;
+    account_id : id;  (** The account to make changes in *)
+    if_in_state : string option;  (** Only apply changes if in this state *)
+    create : (id * email_submission_creation) list option;  (** Map of creation IDs to submissions to create *)
+    update : (id * email_submission_update) list option;  (** Map of IDs to update properties *)
+    destroy : id list option;  (** List of IDs to destroy *)
+    on_success_update_email : (id * email_update) list option;  (** Emails to update if submissions succeed *)
   }
 
+  (** Properties for email submission creation as defined in RFC8621 Section 5.6.
+      Used to create new email submissions.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
+  *)
   and email_submission_creation = {
-    email_id : id;
-    identity_id : id;
-    envelope : envelope option;
-    send_at : utc_date option;
+    email_id : id;  (** ID of the email to send *)
+    identity_id : id;  (** ID of the identity to send from *)
+    envelope : envelope option;  (** Custom envelope, if needed *)
+    send_at : utc_date option;  (** When to send the email, defaults to now *)
   }
 
+  (** Properties for email submission update as defined in RFC8621 Section 5.6.
+      Used to update existing email submissions.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
+  *)
   and email_submission_update = {
-    email_id : id option;
-    identity_id : id option;
-    envelope : envelope option;
-    undo_status : [`canceled] option;
+    email_id : id option;  (** New email ID to use for this submission *)
+    identity_id : id option;  (** New identity ID to use for this submission *)
+    envelope : envelope option;  (** New envelope to use for this submission *)
+    undo_status : [`canceled] option;  (** Set to cancel a pending submission *)
   }
 
-  (** EmailSubmission/set response. See RFC8621 Section 5.6. *)
+  (** EmailSubmission/set response as defined in RFC8621 Section 5.6.
+      Reports the results of email submission changes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-5.6>
+  *)
   type email_submission_set_response = {
-    account_id : id;
-    old_state : string option;
-    new_state : string;
-    created : (id * email_submission) list option;
-    updated : id list option;
-    destroyed : id list option;
-    not_created : (id * set_error) list option;
-    not_updated : (id * set_error) list option;
-    not_destroyed : (id * set_error) list option;
+    account_id : id;  (** The account that was modified *)
+    old_state : string option;  (** The state before processing, if changed *)
+    new_state : string;  (** The current state on the server *)
+    created : (id * email_submission) list option;  (** Map of creation IDs to created submissions *)
+    updated : id list option;  (** List of IDs that were successfully updated *)
+    destroyed : id list option;  (** List of IDs that were successfully destroyed *)
+    not_created : (id * set_error) list option;  (** Map of IDs to errors for failed creates *)
+    not_updated : (id * set_error) list option;  (** Map of IDs to errors for failed updates *)
+    not_destroyed : (id * set_error) list option;  (** Map of IDs to errors for failed destroys *)
   }
 
-  (** {1:identity Identity objects} *)
+  (** {1:identity Identity objects}
+      Identity types as defined in RFC8621 Section 6
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6>
+  *)
 
-  (** Identity for sending mail. See RFC8621 Section 6. *)
+  (** Identity for sending mail as defined in RFC8621 Section 6.
+      Represents an email identity that can be used to send messages.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6>
+  *)
   type identity = {
-    id : id;
-    name : string;
-    email : string;
-    reply_to : email_address list option;
-    bcc : email_address list option;
-    text_signature : string option;
-    html_signature : string option;
-    may_delete : bool;
+    id : id;  (** Server-assigned ID for the identity *)
+    name : string;  (** Display name for the identity *)
+    email : string;  (** Email address for the identity *)
+    reply_to : email_address list option;  (** Reply-To addresses to use when sending *)
+    bcc : email_address list option;  (** BCC addresses to automatically include *)
+    text_signature : string option;  (** Plain text signature for the identity *)
+    html_signature : string option;  (** HTML signature for the identity *)
+    may_delete : bool;  (** Whether this identity can be deleted *)
   }
 
-  (** Identity/get request arguments. See RFC8621 Section 6.1. *)
+  (** Identity/get request arguments as defined in RFC8621 Section 6.1.
+      Used to fetch identities by ID.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.1>
+  *)
   type identity_get_arguments = {
-    account_id : id;
-    ids : id list option;
-    properties : string list option;
+    account_id : id;  (** The account to fetch identities from *)
+    ids : id list option;  (** The IDs of identities to fetch, null means all *)
+    properties : string list option;  (** Properties to return, null means all *)
   }
 
-  (** Identity/get response. See RFC8621 Section 6.1. *)
+  (** Identity/get response as defined in RFC8621 Section 6.1.
+      Contains requested identities.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.1>
+  *)
   type identity_get_response = {
-    account_id : id;
-    state : string;
-    list : identity list;
-    not_found : id list;
+    account_id : id;  (** The account from which identities were fetched *)
+    state : string;  (** A string representing the state on the server *)
+    list : identity list;  (** The list of identities requested *)
+    not_found : id list;  (** IDs requested that could not be found *)
   }
 
-  (** Identity/changes request arguments. See RFC8621 Section 6.2. *)
+  (** Identity/changes request arguments as defined in RFC8621 Section 6.2.
+      Used to get identity changes since a previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.2>
+  *)
   type identity_changes_arguments = {
-    account_id : id;
-    since_state : string;
-    max_changes : unsigned_int option;
+    account_id : id;  (** The account to get changes for *)
+    since_state : string;  (** The previous state to compare to *)
+    max_changes : unsigned_int option;  (** Maximum number of changes to return *)
   }
 
-  (** Identity/changes response. See RFC8621 Section 6.2. *)
+  (** Identity/changes response as defined in RFC8621 Section 6.2.
+      Reports identities that have changed since a previous state.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.2>
+  *)
   type identity_changes_response = {
-    account_id : id;
-    old_state : string;
-    new_state : string;
-    has_more_changes : bool;
-    created : id list;
-    updated : id list;
-    destroyed : id list;
+    account_id : id;  (** The account changes are for *)
+    old_state : string;  (** The state provided in the request *)
+    new_state : string;  (** The current state on the server *)
+    has_more_changes : bool;  (** If true, more changes are available *)
+    created : id list;  (** IDs of identities created since old_state *)
+    updated : id list;  (** IDs of identities updated since old_state *)
+    destroyed : id list;  (** IDs of identities destroyed since old_state *)
   }
 
-  (** Identity/set request arguments. See RFC8621 Section 6.3. *)
+  (** Identity/set request arguments as defined in RFC8621 Section 6.3.
+      Used to create, update, and destroy identities.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
+  *)
   type identity_set_arguments = {
-    account_id : id;
-    if_in_state : string option;
-    create : (id * identity_creation) list option;
-    update : (id * identity_update) list option;
-    destroy : id list option;
+    account_id : id;  (** The account to make changes in *)
+    if_in_state : string option;  (** Only apply changes if in this state *)
+    create : (id * identity_creation) list option;  (** Map of creation IDs to identities to create *)
+    update : (id * identity_update) list option;  (** Map of IDs to update properties *)
+    destroy : id list option;  (** List of IDs to destroy *)
   }
 
+  (** Properties for identity creation as defined in RFC8621 Section 6.3.
+      Used to create new identities.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
+  *)
   and identity_creation = {
-    name : string;
-    email : string;
-    reply_to : email_address list option;
-    bcc : email_address list option;
-    text_signature : string option;
-    html_signature : string option;
+    name : string;  (** Display name for the identity *)
+    email : string;  (** Email address for the identity *)
+    reply_to : email_address list option;  (** Reply-To addresses to use when sending *)
+    bcc : email_address list option;  (** BCC addresses to automatically include *)
+    text_signature : string option;  (** Plain text signature for the identity *)
+    html_signature : string option;  (** HTML signature for the identity *)
   }
 
+  (** Properties for identity update as defined in RFC8621 Section 6.3.
+      Used to update existing identities.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
+  *)
   and identity_update = {
-    name : string option;
-    email : string option;
-    reply_to : email_address list option;
-    bcc : email_address list option;
-    text_signature : string option;
-    html_signature : string option;
+    name : string option;  (** New display name for the identity *)
+    email : string option;  (** New email address for the identity *)
+    reply_to : email_address list option;  (** New Reply-To addresses to use *)
+    bcc : email_address list option;  (** New BCC addresses to automatically include *)
+    text_signature : string option;  (** New plain text signature *)
+    html_signature : string option;  (** New HTML signature *)
   }
 
-  (** Identity/set response. See RFC8621 Section 6.3. *)
+  (** Identity/set response as defined in RFC8621 Section 6.3.
+      Reports the results of identity changes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-6.3>
+  *)
   type identity_set_response = {
-    account_id : id;
-    old_state : string option;
-    new_state : string;
-    created : (id * identity) list option;
-    updated : id list option;
-    destroyed : id list option;
-    not_created : (id * set_error) list option;
-    not_updated : (id * set_error) list option;
-    not_destroyed : (id * set_error) list option;
+    account_id : id;  (** The account that was modified *)
+    old_state : string option;  (** The state before processing, if changed *)
+    new_state : string;  (** The current state on the server *)
+    created : (id * identity) list option;  (** Map of creation IDs to created identities *)
+    updated : id list option;  (** List of IDs that were successfully updated *)
+    destroyed : id list option;  (** List of IDs that were successfully destroyed *)
+    not_created : (id * set_error) list option;  (** Map of IDs to errors for failed creates *)
+    not_updated : (id * set_error) list option;  (** Map of IDs to errors for failed updates *)
+    not_destroyed : (id * set_error) list option;  (** Map of IDs to errors for failed destroys *)
   }
 
-  (** {1:vacation_response VacationResponse objects} *)
+  (** {1:vacation_response VacationResponse objects}
+      Vacation response types as defined in RFC8621 Section 7
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7>
+  *)
 
-  (** Vacation auto-reply setting. See RFC8621 Section 7. *)
+  (** Vacation auto-reply setting as defined in RFC8621 Section 7.
+      Represents an automatic vacation/out-of-office response.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7>
+  *)
   type vacation_response = {
-    id : id;
-    is_enabled : bool;
-    from_date : utc_date option;
-    to_date : utc_date option;
-    subject : string option;
-    text_body : string option;
-    html_body : string option;
+    id : id;  (** Server-assigned ID for the vacation response *)
+    is_enabled : bool;  (** Whether the vacation response is active *)
+    from_date : utc_date option;  (** Start date-time of the vacation period *)
+    to_date : utc_date option;  (** End date-time of the vacation period *)
+    subject : string option;  (** Subject line for the vacation response *)
+    text_body : string option;  (** Plain text body for the vacation response *)
+    html_body : string option;  (** HTML body for the vacation response *)
   }
 
-  (** VacationResponse/get request arguments. See RFC8621 Section 7.2. *)
+  (** VacationResponse/get request arguments as defined in RFC8621 Section 7.2.
+      Used to fetch vacation responses by ID.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.2>
+  *)
   type vacation_response_get_arguments = {
-    account_id : id;
-    ids : id list option;
-    properties : string list option;
+    account_id : id;  (** The account to fetch vacation responses from *)
+    ids : id list option;  (** The IDs of vacation responses to fetch, null means all *)
+    properties : string list option;  (** Properties to return, null means all *)
   }
 
-  (** VacationResponse/get response. See RFC8621 Section 7.2. *)
+  (** VacationResponse/get response as defined in RFC8621 Section 7.2.
+      Contains requested vacation responses.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.2>
+  *)
   type vacation_response_get_response = {
-    account_id : id;
-    state : string;
-    list : vacation_response list;
-    not_found : id list;
+    account_id : id;  (** The account from which vacation responses were fetched *)
+    state : string;  (** A string representing the state on the server *)
+    list : vacation_response list;  (** The list of vacation responses requested *)
+    not_found : id list;  (** IDs requested that could not be found *)
   }
 
-  (** VacationResponse/set request arguments. See RFC8621 Section 7.3. *)
+  (** VacationResponse/set request arguments as defined in RFC8621 Section 7.3.
+      Used to update vacation responses.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.3>
+  *)
   type vacation_response_set_arguments = {
-    account_id : id;
-    if_in_state : string option;
-    update : (id * vacation_response_update) list;
+    account_id : id;  (** The account to make changes in *)
+    if_in_state : string option;  (** Only apply changes if in this state *)
+    update : (id * vacation_response_update) list;  (** Map of IDs to update properties *)
   }
 
+  (** Properties for vacation response update as defined in RFC8621 Section 7.3.
+      Used to update existing vacation responses.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.3>
+  *)
   and vacation_response_update = {
-    is_enabled : bool option;
-    from_date : utc_date option;
-    to_date : utc_date option;
-    subject : string option;
-    text_body : string option;
-    html_body : string option;
+    is_enabled : bool option;  (** Whether the vacation response is active *)
+    from_date : utc_date option;  (** Start date-time of the vacation period *)
+    to_date : utc_date option;  (** End date-time of the vacation period *)
+    subject : string option;  (** Subject line for the vacation response *)
+    text_body : string option;  (** Plain text body for the vacation response *)
+    html_body : string option;  (** HTML body for the vacation response *)
   }
 
-  (** VacationResponse/set response. See RFC8621 Section 7.3. *)
+  (** VacationResponse/set response as defined in RFC8621 Section 7.3.
+      Reports the results of vacation response changes.
+      @see <https://datatracker.ietf.org/doc/html/rfc8621#section-7.3>
+  *)
   type vacation_response_set_response = {
-    account_id : id;
-    old_state : string option;
-    new_state : string;
-    updated : id list option;
-    not_updated : (id * set_error) list option;
+    account_id : id;  (** The account that was modified *)
+    old_state : string option;  (** The state before processing, if changed *)
+    new_state : string;  (** The current state on the server *)
+    updated : id list option;  (** List of IDs that were successfully updated *)
+    not_updated : (id * set_error) list option;  (** Map of IDs to errors for failed updates *)
   }
   
-  (** {1:message_flags Message Flags and Mailbox Attributes} *)
+  (** {1:message_flags Message Flags and Mailbox Attributes}
+      Message flag types as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02
+      @see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute>
+  *)
   
-  (** Flag color defined by the combination of MailFlagBit0, MailFlagBit1, and MailFlagBit2 keywords *)
+  (** Flag color defined by the combination of MailFlagBit0, MailFlagBit1, and MailFlagBit2 keywords
+      as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 Section 3.
+      @see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute#section-3>
+  *)
   type flag_color =
-    | Red     (** Bit pattern 000 *)
-    | Orange  (** Bit pattern 100 *)
-    | Yellow  (** Bit pattern 010 *)
-    | Green   (** Bit pattern 111 *)
-    | Blue    (** Bit pattern 001 *)
-    | Purple  (** Bit pattern 101 *)
-    | Gray    (** Bit pattern 011 *)
+    | Red     (** Bit pattern 000 - default color *)
+    | Orange  (** Bit pattern 100 - MailFlagBit2 set *)
+    | Yellow  (** Bit pattern 010 - MailFlagBit1 set *)
+    | Green   (** Bit pattern 111 - all bits set *)
+    | Blue    (** Bit pattern 001 - MailFlagBit0 set *)
+    | Purple  (** Bit pattern 101 - MailFlagBit2 and MailFlagBit0 set *)
+    | Gray    (** Bit pattern 011 - MailFlagBit1 and MailFlagBit0 set *)
   
-  (** Standard message keywords as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 *)
+  (** Standard message keywords as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 Section 4.1.
+      These are standardized keywords that can be applied to email messages.
+      @see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute#section-4.1>
+  *)
   type message_keyword =
     | Notify         (** Indicate a notification should be shown for this message *)
     | Muted          (** User is not interested in future replies to this thread *)
···
     | MailFlagBit2   (** Bit 2 of the 3-bit flag color pattern *)
     | OtherKeyword of string (** Other non-standard keywords *)
   
-  (** Special mailbox attribute names as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 *)
+  (** Special mailbox attribute names as defined in draft-ietf-mailmaint-messageflag-mailboxattribute-02 Section 4.2.
+      These are standardized attributes for special-purpose mailboxes.
+      @see <https://datatracker.ietf.org/doc/html/draft-ietf-mailmaint-messageflag-mailboxattribute#section-4.2>
+  *)
   type mailbox_attribute =
     | Snoozed    (** Mailbox containing messages that have been snoozed *)
     | Scheduled  (** Mailbox containing messages scheduled to be sent later *)
     | Memos      (** Mailbox containing messages with the $memo keyword *)
     | OtherAttribute of string (** Other non-standard mailbox attributes *)
   
-  (** Functions for working with flag colors *)
+  (** Convert bit values to a flag color
+      @param bit0 Value of bit 0 (least significant bit)
+      @param bit1 Value of bit 1
+      @param bit2 Value of bit 2 (most significant bit)
+      @return The corresponding flag color
+  *)
   val flag_color_of_bits : bool -> bool -> bool -> flag_color
   
-  (** Get bits for a flag color *)
+  (** Get the bit values for a flag color
+      @param color The flag color
+      @return Tuple of (bit2, bit1, bit0) values
+  *)
   val bits_of_flag_color : flag_color -> bool * bool * bool
   
-  (** Check if a message has a flag color based on its keywords *)
+  (** Check if a message has a flag color based on its keywords
+      @param keywords The list of keywords for the message
+      @return True if the message has one or more flag color bits set
+  *)
   val has_flag_color : (keyword * bool) list -> bool
   
-  (** Get the flag color from a message's keywords, if present *)
+  (** Get the flag color from a message's keywords, if present
+      @param keywords The list of keywords for the message
+      @return The flag color if all required bits are present, None otherwise
+  *)
   val get_flag_color : (keyword * bool) list -> flag_color option
   
-  (** Convert a message keyword to its string representation *)
+  (** Convert a message keyword to its string representation
+      @param keyword The message keyword
+      @return String representation with $ prefix (e.g., "$notify")
+  *)
   val string_of_message_keyword : message_keyword -> string
   
-  (** Parse a string into a message keyword *)
+  (** Parse a string into a message keyword
+      @param s The string to parse (with or without $ prefix)
+      @return The corresponding message keyword
+  *)
   val message_keyword_of_string : string -> message_keyword
   
-  (** Convert a mailbox attribute to its string representation *)
+  (** Convert a mailbox attribute to its string representation
+      @param attr The mailbox attribute
+      @return String representation with $ prefix (e.g., "$snoozed")
+  *)
   val string_of_mailbox_attribute : mailbox_attribute -> string
   
-  (** Parse a string into a mailbox attribute *)
+  (** Parse a string into a mailbox attribute
+      @param s The string to parse (with or without $ prefix)
+      @return The corresponding mailbox attribute
+  *)
   val mailbox_attribute_of_string : string -> mailbox_attribute
   
-  (** Get a human-readable representation of a flag color *)
+  (** Get a human-readable representation of a flag color
+      @param color The flag color
+      @return Human-readable name of the color
+  *)
   val human_readable_flag_color : flag_color -> string
   
-  (** Get a human-readable representation of a message keyword *)
+  (** Get a human-readable representation of a message keyword
+      @param keyword The message keyword
+      @return Human-readable description of the keyword
+  *)
   val human_readable_message_keyword : message_keyword -> string
   
-  (** Format email keywords into a human-readable string representation *)
+  (** Format email keywords into a human-readable string representation
+      @param keywords The list of keywords and their values
+      @return Human-readable comma-separated list of keywords
+  *)
   val format_email_keywords : (keyword * bool) list -> string
 end
 
-(** {1 JSON serialization} *)
+(** {1 JSON serialization}
+    Functions for serializing and deserializing JMAP Mail objects to/from JSON
+*)
 
 module Json : sig
   open Types
 
-  (** {2 Helper functions for serialization} *)
+  (** {2 Helper functions for serialization}
+      Utility functions for converting between OCaml types and JSON representation
+  *)
   
+  (** Convert a mailbox role to its string representation
+      @param role The mailbox role
+      @return String representation (e.g., "inbox", "drafts", etc.)
+  *)
   val string_of_mailbox_role : mailbox_role -> string
+  
+  (** Parse a string into a mailbox role
+      @param s The string to parse
+      @return The corresponding mailbox role, or Unknown if not recognized
+  *)
   val mailbox_role_of_string : string -> mailbox_role
   
+  (** Convert an email keyword to its string representation
+      @param keyword The email keyword
+      @return String representation with $ prefix (e.g., "$flagged")
+  *)
   val string_of_keyword : keyword -> string
+  
+  (** Parse a string into an email keyword
+      @param s The string to parse (with or without $ prefix)
+      @return The corresponding email keyword
+  *)
   val keyword_of_string : string -> keyword
 
-  (** {2 Mailbox serialization} *)
+  (** {2 Mailbox serialization}
+      Functions for serializing and deserializing mailbox objects
+  *)
 
   (** TODO:claude - Need to implement all JSON serialization functions 
       for each type we've defined. This would be a substantial amount of
···
   *)
 end
 
-(** {1 API functions} *)
+(** {1 API functions}
+    High-level functions for interacting with JMAP Mail servers
+*)
 
 (** Authentication credentials for a JMAP server *)
 type credentials = {
-  username: string;
-  password: string;
+  username: string;  (** Username for authentication *)
+  password: string;  (** Password for authentication *)
 }
 
 (** Connection to a JMAP mail server *)
 type connection = {
-  session: Jmap.Types.session;
-  config: Jmap.Api.config;
+  session: Jmap.Types.session;  (** Session information from the server *)
+  config: Jmap.Api.config;      (** Configuration for API requests *)
 }
 
 (** Login to a JMAP server and establish a connection
     @param uri The URI of the JMAP server
     @param credentials Authentication credentials
-    @return A connection object if successful 
+    @return A connection object if successful
     
-    TODO:claude *)
+    Creates a new connection to a JMAP server using username/password authentication.
+*)
 val login : 
   uri:string -> 
   credentials:credentials -> 
···
     @param api_token The API token for authentication
     @return A connection object if successful
     
-    TODO:claude *)
+    Creates a new connection to a JMAP server using Bearer token authentication.
+*)
 val login_with_token : 
   uri:string -> 
   api_token:string -> 
···
     @param account_id The account ID to get mailboxes for
     @return A list of mailboxes if successful
     
-    TODO:claude *)
+    Retrieves all mailboxes (folders) in the specified account.
+*)
 val get_mailboxes : 
   connection -> 
   account_id:Jmap.Types.id -> 
···
     @param mailbox_id The mailbox ID to retrieve
     @return The mailbox if found
     
-    TODO:claude *)
+    Retrieves a single mailbox by its ID.
+*)
 val get_mailbox : 
   connection -> 
   account_id:Jmap.Types.id -> 
···
     @param limit Optional limit on number of messages to return
     @return The list of email messages if successful
     
-    TODO:claude *)
+    Retrieves email messages in the specified mailbox, with optional limit.
+*)
 val get_messages_in_mailbox : 
   connection -> 
   account_id:Jmap.Types.id -> 
···
     @param email_id The email ID to retrieve
     @return The email message if found
     
-    TODO:claude *)
+    Retrieves a single email message by its ID.
+*)
 val get_email : 
   connection -> 
   account_id:Jmap.Types.id -> 
···
     @param keyword The message keyword to look for
     @return true if the email has the keyword, false otherwise
     
-    TODO:claude *)
+    Tests whether an email has a particular keyword (flag) set.
+*)
 val has_message_keyword :
   Types.email ->
   Types.message_keyword ->
···
     @param keyword The message keyword to add
     @return Success or error
     
-    TODO:claude *)
+    Adds a keyword (flag) to an email message.
+*)
 val add_message_keyword :
   connection ->
   account_id:Jmap.Types.id ->
···
     @param color The flag color to set
     @return Success or error
     
-    TODO:claude *)
+    Sets a flag color on an email message by setting the appropriate bit flags.
+*)
 val set_flag_color :
   connection ->
   account_id:Jmap.Types.id ->
···
     @param email The email to analyze
     @return List of message keywords
     
-    TODO:claude *)
+    Extracts all message keywords from an email's keyword list.
+*)
 val get_message_keywords :
   Types.email ->
   Types.message_keyword list
···
     @param limit Optional limit on number of emails to return
     @return List of emails with the keyword if successful
     
-    TODO:claude *)
+    Retrieves all emails that have a specific keyword (flag) set.
+*)
 val get_emails_with_keyword :
   connection ->
   account_id:Jmap.Types.id ->
···
   unit ->
   (Types.email list, Jmap.Api.error) result Lwt.t
   
-(** {1 Email Address Utilities} *)
+(** {1 Email Address Utilities}
+    Utilities for working with email addresses
+*)
 
 (** Check if an email address matches a filter string
     @param email The email address to check
···
     @param email The email object to check
     @param pattern The sender filter pattern
     @return True if any sender address matches the filter
+    
+    Tests whether any of an email's sender addresses match the provided pattern.
 *)
 val email_matches_sender : Types.email -> string -> bool