From 606f988ed87b4985d2acfefce2261ddfc809f1e2 Mon Sep 17 00:00:00 2001
From: Devin Ragotzy <devin.ragotzy@gmail.com>
Date: Mon, 3 Aug 2020 11:21:56 -0400
Subject: [PATCH] Add doc comments for cmp traits and use unambiguius paths

---
 ruma-events-macros/src/event.rs |  5 ++++-
 ruma-events/src/event_kinds.rs  | 36 +++++++++++++++++++++++++++++----
 2 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/ruma-events-macros/src/event.rs b/ruma-events-macros/src/event.rs
index 22fe6b41..9e3c960d 100644
--- a/ruma-events-macros/src/event.rs
+++ b/ruma-events-macros/src/event.rs
@@ -382,7 +382,8 @@ fn expand_eq_ord_event(input: &DeriveInput, fields: &[Field]) -> Option<TokenStr
 
         Some(quote! {
             impl #impl_gen ::std::cmp::PartialEq for #ident #ty_gen #where_clause {
-                fn eq(&self, other: &Self) -> bool {
+                /// This checks if two `EventId`s are equal.
+                fn eq(&self, other: &Self) -> ::std::primitive::bool {
                     self.event_id == other.event_id
                 }
             }
@@ -390,12 +391,14 @@ fn expand_eq_ord_event(input: &DeriveInput, fields: &[Field]) -> Option<TokenStr
             impl #impl_gen ::std::cmp::Eq for #ident #ty_gen #where_clause {}
 
             impl #impl_gen ::std::cmp::PartialOrd for #ident #ty_gen #where_clause {
+                /// This compares `EventId`s and orders them lexicographically.
                 fn partial_cmp(&self, other: &Self) -> ::std::option::Option<::std::cmp::Ordering> {
                     self.event_id.partial_cmp(&other.event_id)
                 }
             }
 
             impl #impl_gen ::std::cmp::Ord for #ident #ty_gen #where_clause {
+                /// This compares `EventId`s and orders them lexicographically.
                 fn cmp(&self, other: &Self) -> ::std::cmp::Ordering {
                     self.event_id.cmp(&other.event_id)
                 }
diff --git a/ruma-events/src/event_kinds.rs b/ruma-events/src/event_kinds.rs
index 919c73d2..6710decb 100644
--- a/ruma-events/src/event_kinds.rs
+++ b/ruma-events/src/event_kinds.rs
@@ -16,7 +16,7 @@ pub struct BasicEvent<C: BasicEventContent> {
     pub content: C,
 }
 
-/// Ephemeral room event.
+/// An ephemeral room event.
 #[derive(Clone, Debug, Event)]
 pub struct EphemeralRoomEvent<C: EphemeralRoomEventContent> {
     /// Data specific to the event type.
@@ -33,9 +33,9 @@ pub struct SyncEphemeralRoomEvent<C: EphemeralRoomEventContent> {
     pub content: C,
 }
 
-/// Message event.
+/// A message event.
 ///
-/// `MessageEvent` implements the comparison trait's using only
+/// `MessageEvent` implements the comparison traits using only
 /// the `event_id` field, a sorted list would be sorted lexicographically based on
 /// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
@@ -60,6 +60,10 @@ pub struct MessageEvent<C: MessageEventContent> {
 }
 
 /// A message event without a `room_id`.
+///
+/// `SyncMessageEvent` implements the comparison traits using only
+/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct SyncMessageEvent<C: MessageEventContent> {
     /// Data specific to the event type.
@@ -79,6 +83,10 @@ pub struct SyncMessageEvent<C: MessageEventContent> {
 }
 
 /// A redacted message event.
+///
+/// `RedactedMessageEvent` implements the comparison traits using only
+/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct RedactedMessageEvent<C: RedactedMessageEventContent> {
     /// Data specific to the event type.
@@ -101,6 +109,10 @@ pub struct RedactedMessageEvent<C: RedactedMessageEventContent> {
 }
 
 /// A redacted message event without a `room_id`.
+///
+/// `RedactedSyncMessageEvent` implements the comparison traits using only
+/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct RedactedSyncMessageEvent<C: RedactedMessageEventContent> {
     /// Data specific to the event type.
@@ -120,7 +132,11 @@ pub struct RedactedSyncMessageEvent<C: RedactedMessageEventContent> {
     pub unsigned: RedactedSyncUnsigned,
 }
 
-/// State event.
+/// A state event.
+///
+/// `StateEvent` implements the comparison traits using only
+/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct StateEvent<C: StateEventContent> {
     /// Data specific to the event type.
@@ -152,6 +168,10 @@ pub struct StateEvent<C: StateEventContent> {
 }
 
 /// A state event without a `room_id`.
+///
+/// `SyncStateEvent` implements the comparison traits using only
+/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct SyncStateEvent<C: StateEventContent> {
     /// Data specific to the event type.
@@ -197,6 +217,10 @@ pub struct StrippedStateEvent<C: StateEventContent> {
 }
 
 /// A redacted state event.
+///
+/// `RedactedStateEvent` implements the comparison traits using only
+/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct RedactedStateEvent<C: RedactedStateEventContent> {
     /// Data specific to the event type.
@@ -225,6 +249,10 @@ pub struct RedactedStateEvent<C: RedactedStateEventContent> {
 }
 
 /// A redacted state event without a `room_id`.
+///
+/// `RedactedSyncStateEvent` implements the comparison traits using only
+/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct RedactedSyncStateEvent<C: RedactedStateEventContent> {
     /// Data specific to the event type.