From 66383551d150e87fdd689e03716841faad20187c Mon Sep 17 00:00:00 2001
From: Bram van den Heuvel <bram.vdh1999@gmail.com>
Date: Wed, 12 Apr 2023 12:00:08 +0200
Subject: [PATCH] Update Event documentation

---
 src/Matrix/Event.elm | 35 +++++++++++++++++++++++++----------
 1 file changed, 25 insertions(+), 10 deletions(-)

diff --git a/src/Matrix/Event.elm b/src/Matrix/Event.elm
index b547a20..ee1623e 100644
--- a/src/Matrix/Event.elm
+++ b/src/Matrix/Event.elm
@@ -1,19 +1,29 @@
 module Matrix.Event exposing
-    ( Event, eventType, content, stateKey
-    , eventId, roomId, sender, originServerTs, redactedBecause
+    ( Event, eventId
+    , content, eventType, stateKey
+    , roomId, sender, originServerTs, redactedBecause
     )
 
-{-| This module allows you to read Matrix events.
+{-| This module allows you to read and manipulate events in a Matrix room.
 
 
 # Event
 
-@docs Event, eventType, content, stateKey
+@docs Event, eventId
 
 
-## Getting metadata
+## Reading data
 
-@docs eventId, roomId, sender, originServerTs, redactedBecause
+Every event has a JSON value as its body, which was sent by the sender.
+The `eventType` indicates the format that you should expect of the JSON value,
+and the `stateKey` indicates whether it changes the room state or not.
+
+@docs content, eventType, stateKey
+
+Other than that, there's other information that you'll be able to look up.
+This is considered metadata that will help you put the events in context.
+
+@docs roomId, sender, originServerTs, redactedBecause
 
 -}
 
@@ -22,7 +32,7 @@ import Json.Encode as E
 import Time
 
 
-{-| The `Event` type relates to an event type in a room.
+{-| The `Event` type relates to an event type in a room. This can both
 -}
 type alias Event =
     Internal.Event
@@ -35,7 +45,8 @@ content =
     Internal.content
 
 
-{-| Get the event's id.
+{-| Get the event's id. Event ids are usually named using the Java package naming convention,
+for example `org.example.custom.event`.
 -}
 eventId : Event -> String
 eventId =
@@ -43,6 +54,10 @@ eventId =
 
 
 {-| Timestamp of when this event was first received on the original homeserver.
+
+**NOTE:** You shouldn't rely on this value to determine the chronological order of events.
+Matrix has many servers, and a homeserver can spoof this value.
+
 -}
 originServerTs : Event -> Time.Posix
 originServerTs =
@@ -65,7 +80,7 @@ sender =
 
 {-| The optional statekey of the event.
 
-Whether this contains a value also dictates whether it is a state event or a message event.
+Whether this contains a value also dictates whether the event updates the room state.
 
 -}
 stateKey : Event -> Maybe String
@@ -73,7 +88,7 @@ stateKey =
     Internal.stateKey
 
 
-{-| This is the type of the event's content. For example, `m.room.message` indicates that it was a message.
+{-| The type of the event's content. For example, `m.room.message` indicates that it was a message.
 -}
 eventType : Event -> String
 eventType =