Update documentation

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<EventType>`.
 #[proc_macro]
 pub fn ruma_event(input: TokenStream) -> TokenStream {
     let ruma_event_input = syn::parse_macro_input!(input as RumaEventInput);

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::<EventResult<StartEventContent>>(
                 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"]}"#

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<EventType>`. 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<ContentType>` 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;