Fix / improve event handler documentation
parent
bf8945430f
commit
67912f3768
|
@ -879,13 +879,13 @@ impl Client {
|
||||||
|
|
||||||
/// Register a handler for a specific event type.
|
/// Register a handler for a specific event type.
|
||||||
///
|
///
|
||||||
/// The handler is a function or closue with one or more arguments. The
|
/// The handler is a function or closure with one or more arguments. The
|
||||||
/// first argument is the event itself. All additional arguments are
|
/// first argument is the event itself. All additional arguments are
|
||||||
/// "context" arguments: They have to implement [`EventHandlerContext`][].
|
/// "context" arguments: They have to implement [`EventHandlerContext`].
|
||||||
/// This trait is named that way because most of the types implementing it
|
/// This trait is named that way because most of the types implementing it
|
||||||
/// give additional context about an event: The room it was in, its raw form
|
/// give additional context about an event: The room it was in, its raw form
|
||||||
/// and other similar things. As an exception to this,
|
/// and other similar things. As an exception to this,
|
||||||
/// [`matrix_sdk::Client`] also implements the `EventHandlerContext` trait
|
/// [`Client`] also implements the `EventHandlerContext` trait
|
||||||
/// so you don't have to clone your client into the event handler manually.
|
/// so you don't have to clone your client into the event handler manually.
|
||||||
///
|
///
|
||||||
/// Invalid context arguments, for example a [`Room`][room::Room] as an
|
/// Invalid context arguments, for example a [`Room`][room::Room] as an
|
||||||
|
@ -901,21 +901,39 @@ impl Client {
|
||||||
/// use matrix_sdk::{
|
/// use matrix_sdk::{
|
||||||
/// room::Room,
|
/// room::Room,
|
||||||
/// ruma::events::{
|
/// ruma::events::{
|
||||||
|
/// macros::EventContent,
|
||||||
/// push_rules::PushRulesEvent,
|
/// push_rules::PushRulesEvent,
|
||||||
/// room::{message::MessageEventContent, topic::TopicEventContent},
|
/// room::{message::MessageEventContent, topic::TopicEventContent},
|
||||||
/// SyncMessageEvent, SyncStateEvent,
|
/// Int, MilliSecondsSinceUnixEpoch, SyncMessageEvent, SyncStateEvent,
|
||||||
/// },
|
/// },
|
||||||
/// Client,
|
/// Client,
|
||||||
/// };
|
/// };
|
||||||
|
/// use serde::{Deserialize, Serialize};
|
||||||
///
|
///
|
||||||
/// client.register_event_handler(
|
/// client.register_event_handler(
|
||||||
/// |msg: SyncMessageEvent<MessageEventContent>, room: Room, client: Client| async move {
|
/// |ev: SyncMessageEvent<MessageEventContent>, room: Room, client: Client| async move {
|
||||||
/// // Common usage: Room event plus room and client.
|
/// // Common usage: Room event plus room and client.
|
||||||
/// },
|
/// },
|
||||||
/// );
|
/// );
|
||||||
/// client.register_event_handler(|ev: SyncStateEvent<TopicEventContent>| async move {
|
/// client.register_event_handler(|ev: SyncStateEvent<TopicEventContent>| async move {
|
||||||
/// // Also possible: Omit any or all arguments after the first.
|
/// // Also possible: Omit any or all arguments after the first.
|
||||||
/// });
|
/// });
|
||||||
|
///
|
||||||
|
/// // Custom events work exactly the same way, you just need to declare the content struct and
|
||||||
|
/// // use the EventContent derive macro on it.
|
||||||
|
/// #[derive(Clone, Debug, Deserialize, Serialize, EventContent)]
|
||||||
|
/// #[ruma_event(type = "org.shiny_new_2fa.token", kind = Message)]
|
||||||
|
/// struct TokenEventContent {
|
||||||
|
/// token: String,
|
||||||
|
/// #[serde(rename = "exp")]
|
||||||
|
/// expires_at: MilliSecondsSinceUnixEpoch,
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// client.register_event_handler(
|
||||||
|
/// |ev: SyncMessageEvent<TokenEventContent>, room: Room| async move {
|
||||||
|
/// todo!("Display the token");
|
||||||
|
/// },
|
||||||
|
/// );
|
||||||
/// ```
|
/// ```
|
||||||
pub async fn register_event_handler<Ev, Ctx, H>(&self, handler: H)
|
pub async fn register_event_handler<Ev, Ctx, H>(&self, handler: H)
|
||||||
where
|
where
|
||||||
|
|
|
@ -50,7 +50,7 @@ pub trait SyncEvent {
|
||||||
/// specifically:
|
/// specifically:
|
||||||
///
|
///
|
||||||
/// * They must have at least one argument, which is the event itself, a type
|
/// * They must have at least one argument, which is the event itself, a type
|
||||||
/// that implements [`StaticEvent`]. Any additional arguments need to
|
/// that implements [`SyncEvent`]. Any additional arguments need to
|
||||||
/// implement the [`EventHandlerContext`] trait.
|
/// implement the [`EventHandlerContext`] trait.
|
||||||
/// * Their return type has to be one of: `()`, `Result<(), impl
|
/// * Their return type has to be one of: `()`, `Result<(), impl
|
||||||
/// std::error::Error>` or `anyhow::Result<()>` (requires the `anyhow` Cargo
|
/// std::error::Error>` or `anyhow::Result<()>` (requires the `anyhow` Cargo
|
||||||
|
|
|
@ -52,6 +52,7 @@
|
||||||
//! `require_auth_for_profile_requests`. Enabled by default.
|
//! `require_auth_for_profile_requests`. Enabled by default.
|
||||||
//! * `appservice`: Enables low-level appservice functionality. For an
|
//! * `appservice`: Enables low-level appservice functionality. For an
|
||||||
//! high-level API there's the `matrix-sdk-appservice` crate
|
//! high-level API there's the `matrix-sdk-appservice` crate
|
||||||
|
//! * `anyhow`: Support for returning `anyhow::Result<()>` from event handlers.
|
||||||
|
|
||||||
#![deny(
|
#![deny(
|
||||||
missing_debug_implementations,
|
missing_debug_implementations,
|
||||||
|
|
Loading…
Reference in New Issue