rust: Add method docs!

Author: svix-jplatte

rust/src/api/application.rs

@@ -22,6 +22,7 @@ impl<'a> Application<'a> {
         Self { cfg }
     }
 
+    /// List of all the organization's applications.
     pub async fn list(
         &self,
         options: Option<ApplicationListOptions>,
@@ -43,6 +44,7 @@ impl<'a> Application<'a> {
         .await
     }
 
+    /// Create a new application.
     pub async fn create(
         &self,
         application_in: ApplicationIn,
@@ -60,6 +62,8 @@ impl<'a> Application<'a> {
         .await
     }
 
+    /// Create the application with the given ID, or create a new one if it
+    /// doesn't exist yet.
     pub async fn get_or_create(
         &self,
         application_in: ApplicationIn,
@@ -77,6 +81,7 @@ impl<'a> Application<'a> {
         .await
     }
 
+    /// Get an application.
     pub async fn get(&self, app_id: String) -> Result<ApplicationOut> {
         application_api::v1_period_application_period_get(
             self.cfg,
@@ -85,6 +90,7 @@ impl<'a> Application<'a> {
         .await
     }
 
+    /// Update an application.
     pub async fn update(
         &self,
         app_id: String,
@@ -100,6 +106,7 @@ impl<'a> Application<'a> {
         .await
     }
 
+    /// Delete an application.
     pub async fn delete(&self, app_id: String) -> Result<()> {
         application_api::v1_period_application_period_delete(
             self.cfg,
@@ -108,6 +115,7 @@ impl<'a> Application<'a> {
         .await
     }
 
+    /// Partially update an application.
     pub async fn patch(
         &self,
         app_id: String,

rust/src/api/authentication.rs

@@ -1,5 +1,6 @@
 use super::PostOptions;
 use crate::{apis::authentication_api, error::Result, models::*, Configuration};
+
 pub struct Authentication<'a> {
     cfg: &'a Configuration,
 }
@@ -25,26 +26,33 @@ impl<'a> Authentication<'a> {
         .await
     }
 
+    /// Use this function to get magic links (and authentication codes) for
+    /// connecting your users to the Consumer Application Portal.
     pub async fn app_portal_access(
         &self,
         app_id: String,
         app_portal_access_in: AppPortalAccessIn,
         options: Option<PostOptions>,
     ) -> Result<AppPortalAccessOut> {
-        let options = options.unwrap_or_default();
+        let PostOptions { idempotency_key } = options.unwrap_or_default();
+
         authentication_api::v1_period_authentication_period_app_portal_access(
             self.cfg,
             authentication_api::V1PeriodAuthenticationPeriodAppPortalAccessParams {
                 app_id,
                 app_portal_access_in,
-                idempotency_key: options.idempotency_key,
+                idempotency_key,
             },
         )
         .await
     }
 
+    /// Logout an app token.
+    ///
+    /// Trying to log out other tokens will fail.
     pub async fn logout(&self, options: Option<PostOptions>) -> Result<()> {
         let PostOptions { idempotency_key } = options.unwrap_or_default();
+
         authentication_api::v1_period_authentication_period_logout(
             self.cfg,
             authentication_api::V1PeriodAuthenticationPeriodLogoutParams { idempotency_key },

rust/src/api/endpoint.rs

@@ -35,6 +35,7 @@ impl<'a> Endpoint<'a> {
         Self { cfg }
     }
 
+    /// List the application's endpoints.
     pub async fn list(
         &self,
         app_id: String,
@@ -58,6 +59,10 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Create a new endpoint for the application.
+    ///
+    /// When `secret` is `null` the secret is automatically generated
+    /// (recommended)
     pub async fn create(
         &self,
         app_id: String,
@@ -77,6 +82,7 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Get an endpoint.
     pub async fn get(&self, app_id: String, endpoint_id: String) -> Result<EndpointOut> {
         endpoint_api::v1_period_endpoint_period_get(
             self.cfg,
@@ -88,6 +94,7 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Update an endpoint.
     pub async fn update(
         &self,
         app_id: String,
@@ -105,6 +112,7 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Delete an endpoint.
     pub async fn delete(&self, app_id: String, endpoint_id: String) -> Result<()> {
         endpoint_api::v1_period_endpoint_period_delete(
             self.cfg,
@@ -116,6 +124,7 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Partially update an endpoint.
     pub async fn patch(
         &self,
         app_id: String,
@@ -133,6 +142,11 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Get the endpoint's signing secret.
+    ///
+    /// This is used to verify the authenticity of the webhook.
+    /// For more information please refer to
+    /// [the consuming webhooks docs](https://docs.svix.com/consuming-webhooks/).
     pub async fn get_secret(
         &self,
         app_id: String,
@@ -148,6 +162,9 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Rotates the endpoint's signing secret.
+    ///
+    /// The previous secret will remain valid for the next 24 hours.
     pub async fn rotate_secret(
         &self,
         app_id: String,
@@ -166,6 +183,10 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Resend all failed messages since a given time.
+    ///
+    /// Messages that were sent successfully, even if failed initially, are not
+    /// resent.
     pub async fn recover(
         &self,
         app_id: String,
@@ -185,6 +206,7 @@ impl<'a> Endpoint<'a> {
         Ok(())
     }
 
+    /// Get the additional headers to be sent with the webhook
     pub async fn get_headers(
         &self,
         app_id: String,
@@ -200,6 +222,7 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Set the additional headers to be sent with the webhook
     pub async fn update_headers(
         &self,
         app_id: String,
@@ -217,6 +240,7 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Partially set the additional headers to be sent with the webhook
     pub async fn patch_headers(
         &self,
         app_id: String,
@@ -234,13 +258,15 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Get basic statistics for the endpoint.
     pub async fn get_stats(
         &self,
         app_id: String,
         endpoint_id: String,
         options: Option<EndpointStatsOptions>,
     ) -> Result<EndpointStats> {
         let EndpointStatsOptions { since, until } = options.unwrap_or_default();
+
         endpoint_api::v1_period_endpoint_period_get_stats(
             self.cfg,
             endpoint_api::V1PeriodEndpointPeriodGetStatsParams {
@@ -253,6 +279,10 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Replays messages to the endpoint.
+    ///
+    /// Only messages that were created after `since` will be sent. Messages
+    /// that were previously sent to the endpoint are not resent.
     pub async fn replay_missing(
         &self,
         app_id: String,
@@ -274,6 +304,7 @@ impl<'a> Endpoint<'a> {
         Ok(())
     }
 
+    /// Get the transformation code associated with this endpoint
     pub async fn transformation_get(
         &self,
         app_id: String,
@@ -289,6 +320,7 @@ impl<'a> Endpoint<'a> {
         .await
     }
 
+    /// Set or unset the transformation code associated with this endpoint
     pub async fn transformation_partial_update(
         &self,
         app_id: String,
@@ -303,10 +335,10 @@ impl<'a> Endpoint<'a> {
                 endpoint_transformation_in,
             },
         )
-        .await?;
-        Ok(())
+        .await
     }
 
+    /// Send an example message for an event
     pub async fn send_example(
         &self,
         app_id: String,

rust/src/api/event_type.rs

@@ -27,6 +27,7 @@ impl<'a> EventType<'a> {
         Self { cfg }
     }
 
+    /// Return the list of event types.
     pub async fn list(
         &self,
         options: Option<EventTypeListOptions>,
@@ -52,6 +53,12 @@ impl<'a> EventType<'a> {
         .await
     }
 
+    /// Create new or unarchive existing event type.
+    ///
+    /// Unarchiving an event type will allow endpoints to filter on it and
+    /// messages to be sent with it. Endpoints filtering on the event type
+    /// before archival will continue to filter on it. This operation does
+    /// not preserve the description and schemas.
     pub async fn create(
         &self,
         event_type_in: EventTypeIn,
@@ -69,6 +76,7 @@ impl<'a> EventType<'a> {
         .await
     }
 
+    /// Get an event type.
     pub async fn get(&self, event_type_name: String) -> Result<EventTypeOut> {
         event_type_api::v1_period_event_type_period_get(
             self.cfg,
@@ -77,6 +85,7 @@ impl<'a> EventType<'a> {
         .await
     }
 
+    /// Update an event type.
     pub async fn update(
         &self,
         event_type_name: String,
@@ -92,6 +101,7 @@ impl<'a> EventType<'a> {
         .await
     }
 
+    /// Partially update an event type.
     pub async fn patch(
         &self,
         event_type_name: String,
@@ -107,6 +117,12 @@ impl<'a> EventType<'a> {
         .await
     }
 
+    /// Archive an event type.
+    ///
+    /// Endpoints already configured to filter on an event type will continue to
+    /// do so after archival. However, new messages can not be sent with it
+    /// and endpoints can not filter on it. An event type can be unarchived
+    /// with the create operation.
     pub async fn delete(&self, event_type_name: String) -> Result<()> {
         event_type_api::v1_period_event_type_period_delete(
             self.cfg,
@@ -118,6 +134,12 @@ impl<'a> EventType<'a> {
         .await
     }
 
+    /// Given an OpenAPI spec, create new or update existing event types.
+    ///
+    /// If an existing `archived` event type is updated, it will be unarchived.
+    ///
+    /// The importer will convert all webhooks found in the either the
+    /// `webhooks` or `x-webhooks` top-level.
     pub async fn import_openapi(
         &self,
         event_type_import_open_api_in: EventTypeImportOpenApiIn,

rust/src/api/integration.rs

@@ -22,6 +22,7 @@ impl<'a> Integration<'a> {
         Self { cfg }
     }
 
+    /// List the application's integrations.
     pub async fn list(
         &self,
         app_id: String,
@@ -45,6 +46,7 @@ impl<'a> Integration<'a> {
         .await
     }
 
+    /// Create an integration.
     pub async fn create(
         &self,
         app_id: String,
@@ -64,6 +66,7 @@ impl<'a> Integration<'a> {
         .await
     }
 
+    /// Get an integration.
     pub async fn get(&self, app_id: String, integ_id: String) -> Result<IntegrationOut> {
         integration_api::v1_period_integration_period_get(
             self.cfg,
@@ -72,6 +75,7 @@ impl<'a> Integration<'a> {
         .await
     }
 
+    /// Update an integration.
     pub async fn update(
         &self,
         app_id: String,
@@ -89,6 +93,7 @@ impl<'a> Integration<'a> {
         .await
     }
 
+    /// Delete an integration.
     pub async fn delete(&self, app_id: String, integ_id: String) -> Result<()> {
         integration_api::v1_period_integration_period_delete(
             self.cfg,
@@ -97,6 +102,7 @@ impl<'a> Integration<'a> {
         .await
     }
 
+    /// Get an integration's key.
     pub async fn get_key(&self, app_id: String, integ_id: String) -> Result<IntegrationKeyOut> {
         integration_api::v1_period_integration_period_get_key(
             self.cfg,
@@ -105,6 +111,8 @@ impl<'a> Integration<'a> {
         .await
     }
 
+    /// Rotate the integration's key. The previous key will be immediately
+    /// revoked.
     pub async fn rotate_key(&self, app_id: String, integ_id: String) -> Result<IntegrationKeyOut> {
         integration_api::v1_period_integration_period_rotate_key(
             self.cfg,