diff --git a/bridge/svix-bridge-types/src/lib.rs b/bridge/svix-bridge-types/src/lib.rs index c0ef38465..6573d53f4 100644 --- a/bridge/svix-bridge-types/src/lib.rs +++ b/bridge/svix-bridge-types/src/lib.rs @@ -259,6 +259,7 @@ pub struct CreateMessageRequest { } /// Receivers convert HTTP bodies into messages forwarded to (currently only) message queues, etc. +/// /// The `payload` field represents the message body given to the producer, and other fields may be /// added in the future allowing transformations to dynamically customize the producer behavior. #[derive(Clone, Deserialize, Serialize)] diff --git a/server/svix-server/src/core/idempotency.rs b/server/svix-server/src/core/idempotency.rs index cec5344b2..581153535 100644 --- a/server/svix-server/src/core/idempotency.rs +++ b/server/svix-server/src/core/idempotency.rs @@ -1,9 +1,12 @@ // SPDX-FileCopyrightText: © 2022 Svix Authors // SPDX-License-Identifier: MIT -//! Defines idempotency middleware for the Axum server which first looks up the given key for an -//! existing response before routing to the given endpoint's function, and caches any such results -//! such that subsequent requests to that endpoint with the same key will return the same response. +//! Idempotency middleware for the Axum server. +//! +//! The middleware first looks up the given key for an existing response before +//! routing to the given endpoint's function, and caches any such results +//! such that subsequent requests to that endpoint with the same key will return +//! the same response. //! //! Responses are cached for twelve hours by default. diff --git a/server/svix-server/src/error.rs b/server/svix-server/src/error.rs index 2445d7f6f..d73998222 100644 --- a/server/svix-server/src/error.rs +++ b/server/svix-server/src/error.rs @@ -431,9 +431,11 @@ impl From for Error { } } -/// Utility function for Converting a [`DbErr`] into an [`HttpError`] (wrapped by [`Error`]) on the -/// error "duplicate key value violates unique constraint". This is to be used in `map_err` calls -/// on creation/update of records +/// Utility function for Converting a [`DbErr`] into an [`Error`]. +/// +/// The error "duplicate key value violates unique constraint" is converted to +/// an HTTP "conflict" error. This is to be used in `map_err` calls on +/// creation/update of records. pub fn http_error_on_conflict(db_err: DbErr) -> Error { if is_conflict_err(&db_err) { HttpError::conflict(None, None).into() diff --git a/server/svix-server/src/v1/utils/mod.rs b/server/svix-server/src/v1/utils/mod.rs index ea6f7696c..d70c4a9fa 100644 --- a/server/svix-server/src/v1/utils/mod.rs +++ b/server/svix-server/src/v1/utils/mod.rs @@ -756,6 +756,7 @@ pub struct EventTypeNamePath { } /// JsonStatus is a wrapper over `axum::extract::Json` as a handler output. +/// /// Setting the `STATUS` const parameter automatically sets the response /// status code, as well as inserting it into the aide documentation. pub struct JsonStatus(pub T); @@ -793,10 +794,12 @@ impl OperationOutput for JsonStatu } /// JsonStatusUpsert is a wrapper over `axum::extract::Json` as a handler -/// output. It is a special casing of `JsonStatus` for situations where a -/// resource is either being updated or created within the same operation. In -/// case of `Updated` HTTP 200 OK is returned, in case of `Created` HTTP 201 -/// CREATED is returned. +/// output. +/// +/// It is a special casing of `JsonStatus` for situations where a resource is +/// either being updated or created within the same operation. In case of +/// `Updated` HTTP 200 OK is returned, in case of `Created` HTTP 201 CREATED +/// is returned. pub enum JsonStatusUpsert { Updated(T), Created(T), diff --git a/server/svix-server/src/v1/utils/patch.rs b/server/svix-server/src/v1/utils/patch.rs index 6c26dde82..e4f1a9abc 100644 --- a/server/svix-server/src/v1/utils/patch.rs +++ b/server/svix-server/src/v1/utils/patch.rs @@ -7,13 +7,15 @@ use schemars::JsonSchema; use serde::{Deserialize, Serialize}; use validator::Validate; -/// This is an enum that will wrap every nullable field for a PATCH request. Nonnullable fields can -/// be represented via an [`UnrequiredField`]. This differs from an [`Option`] in that it -/// distinguishes null values and absent values such that an optional value in a model may be made -/// None via PATCHing while allowing omitted fields to be skipped when updating. +/// This is an enum that will wrap every nullable field for a PATCH request. /// -/// NOTE: You must tag these fields with `#[serde(default)]` in order for the serialization to work -/// correctly. +/// Nonnullable fields can be represented via an [`UnrequiredField`]. This +/// differs from an [`Option`] in that it distinguishes null values and absent +/// values such that an optional value in a model may be made `None` via +/// PATCHing while allowing omitted fields to be skipped when updating. +/// +/// NOTE: You must tag these fields with `#[serde(default)]` in order for the +/// serialization to work correctly. #[derive(Debug)] pub enum UnrequiredNullableField { Absent, @@ -21,14 +23,16 @@ pub enum UnrequiredNullableField { Some(T), } -/// This enum is a non-nullable equivalent to [`UnrequiredNullableField`]. This is effectively an -/// [`Option`] with the additional context that any field which uses this type is a member of a -/// PATCH request model and that the field may be absent, meaning it is not to be updated. In -/// comparison, [`Option`]s are used in other [`ModelIn`]s to define a field, that when absent, -/// is `null`. +/// This enum is a non-nullable equivalent to [`UnrequiredNullableField`]. +/// +/// This is effectively an [`Option`] with the additional context that any field +/// which uses this type is a member of a PATCH request model and that the field +/// may be absent, meaning it is not to be updated. In comparison, [`Option`]s +/// are used in other [`ModelIn`]s to define a field, that when absent, is +/// `null`. /// -/// NOTE: You must tag these fields with `#[serde(default)]` in order for the serialization to work -/// correctly. +/// NOTE: You must tag these fields with `#[serde(default)]` in order for the +/// serialization to work correctly. #[derive(Debug)] pub enum UnrequiredField { Absent, diff --git a/server/svix-server_derive/src/lib.rs b/server/svix-server_derive/src/lib.rs index b734ab266..97c8907c2 100644 --- a/server/svix-server_derive/src/lib.rs +++ b/server/svix-server_derive/src/lib.rs @@ -66,10 +66,11 @@ pub fn derive_model_out(input: proc_macro::TokenStream) -> proc_macro::TokenStre } #[proc_macro_attribute] -/// Attribute macro for axum/aide handler functions that creates a new function -/// with the same name as the handler, suffixed with `_operation`, that acts as -/// an operation transformation function, automatically setting the operation -/// ID, summary and description. +/// Generate an aide operation transform for an axum handler function. +/// +/// The generated function has the same name as the handler, suffixed with +/// `_operation`. It automatically sets the operation ID, summary and +/// description. /// /// # Example /// ```ignore