From c925cd13f12234af2a4ab85b2af724caaea55c52 Mon Sep 17 00:00:00 2001 From: Jonas Platte Date: Wed, 23 Oct 2019 01:42:06 +0200 Subject: [PATCH] Update documentation --- ruma-events-macros/src/lib.rs | 9 ++------- src/key/verification/start.rs | 2 +- src/lib.rs | 32 ++++++++++++++------------------ 3 files changed, 17 insertions(+), 26 deletions(-) diff --git a/ruma-events-macros/src/lib.rs b/ruma-events-macros/src/lib.rs index 6b7ea701..5fd98f9a 100644 --- a/ruma-events-macros/src/lib.rs +++ b/ruma-events-macros/src/lib.rs @@ -122,13 +122,8 @@ mod parse; /// /// The event type and content type will have copies generated inside a private `raw` module. These /// "raw" versions are the same, except they implement `serde::Deserialize`. An implementation of -/// `std::str::FromStr` (and for completeness, `std::convert::TryFrom<&str>`) will be provided, -/// which will allow the user to call `parse` on a string slice of JSON data in attempt to convert -/// into the event type. `FromStr` attempts to deserialize the type using the "raw" version. If -/// deserialization fails, an error is returned to the user. If deserialization succeeds, a value of -/// the public event type will be populated from the raw version's fields and returned. If any -/// semantic error is found after deserialization, a `serde_json::Value` of the deserialized data -/// will be returned in an `InvalidEvent`. +/// `FromRaw` will be provided, which will allow the user to deserialize the event type as +/// `EventResult`. #[proc_macro] pub fn ruma_event(input: TokenStream) -> TokenStream { let ruma_event_input = syn::parse_macro_input!(input as RumaEventInput); diff --git a/src/key/verification/start.rs b/src/key/verification/start.rs index f9a17336..b06174ff 100644 --- a/src/key/verification/start.rs +++ b/src/key/verification/start.rs @@ -442,7 +442,7 @@ mod tests { .unwrap(), ); - // Deserialize the content struct separately to verify `FromStr` is implemented for it. + // Deserialize the content struct separately to verify `TryFromRaw` is implemented for it. assert_eq!( serde_json::from_str::>( r#"{"from_device":"123","transaction_id":"456","method":"m.sas.v1","hashes":["sha256"],"key_agreement_protocols":["curve25519"],"message_authentication_codes":["hkdf-hmac-sha256"],"short_authentication_string":["decimal"]}"# diff --git a/src/lib.rs b/src/lib.rs index d92133ee..85186e3d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -73,19 +73,18 @@ //! # Serialization and deserialization //! //! All concrete event types in ruma-events can be serialized via the `Serialize` trait from -//! [serde](https://serde.rs/) and can be deserialized from a `&str` of JSON data via the `FromStr` -//! trait from the standard library. (`TryFrom<&str>` is also implemented and can be used in place -//! of `FromStr` if preferred.) Supporting types for each event generally implement serde's -//! `Deserialize` trait directly. In order to handle incoming data that may not conform to -//! ruma-events's strict definitions of event structures, deserializing from JSON will return an -//! `InvalidEvent` on error. This error covers both invalid JSON data as well as valid JSON that -//! doesn't match the structure expected by ruma-events's event types. In the latter case, the error -//! exposes the deserialized `serde_json::Value` so that developers can still work with the received -//! event data. This also makes it possible to deserialize a collection of events without the entire +//! [serde](https://serde.rs/) and can be deserialized from as `EventResult`. In order to +//! handle incoming data that may not conform to `ruma-events`' strict definitions of event +//! structures, deserialization will return `EventResult::Err` on error. This error covers both +//! structurally invalid JSON data as well as structurally valid JSON that doesn't fulfill +//! additional constraints the matrix specification defines for some event types. The error exposes +//! the deserialized `serde_json::Value` so that developers can still work with the received +//! event data. This makes it possible to deserialize a collection of events without the entire //! collection failing to deserialize due to a single invalid event. The "content" type for each -//! event also implements `Serialize` and either `FromStr` (for dedicated content types) or -//! `Deserialize` (when the content is a type alias), allowing content to be converted to and from -//! JSON indepedently of the surrounding event structure, if needed. +//! event also implements `Serialize` and either `TryFromRaw` (enabling usage as +//! `EventResult` for dedicated content types) or `Deserialize` (when the content is a +//! type alias), allowing content to be converted to and from JSON indepedently of the surrounding +//! event structure, if needed. //! //! # Collections //! @@ -195,9 +194,9 @@ impl InvalidEvent { InvalidEvent::Validation(err) => err.message.clone(), InvalidEvent::__Nonexhaustive => { panic!("__Nonexhaustive enum variant is not intended for use.") + } } } - } /// The `serde_json::Value` representation of the invalid event. pub fn json(&self) -> &Value { @@ -239,13 +238,13 @@ impl Error for InvalidEvent {} #[derive(Clone, Debug)] pub struct DeserializationError { message: String, - json: Value, + json: Value, } /// An error that occured during raw event validation. #[derive(Clone, Debug)] pub struct ValidationError { - message: String, + message: String, json: Value, } @@ -359,9 +358,6 @@ where } /// An error when attempting to create a value from a string via the `FromStr` trait. -/// -/// This error type is only used for simple enums with unit variants. Event deserialization through -/// the `FromStr` trait returns an `InvalidEvent` on error. #[derive(Clone, Copy, Eq, Debug, Hash, PartialEq)] pub struct FromStrError;