From 186c92c5156a63b7154a4fbfb8eeb7095a9338d2 Mon Sep 17 00:00:00 2001
From: Bram van den Heuvel <bram.vdh1999@gmail.com>
Date: Fri, 17 Feb 2023 11:30:59 +0100
Subject: [PATCH] Documentation for Credentials type

---
 src/Internal/Api/Sync/Api.elm       |  1 +
 src/Internal/Api/Sync/V2/Upcast.elm |  8 ++++++++
 src/Internal/Values/Credentials.elm | 32 +++++++++++++++++++++++++++++
 3 files changed, 41 insertions(+)

diff --git a/src/Internal/Api/Sync/Api.elm b/src/Internal/Api/Sync/Api.elm
index 886c54b..7b0fe05 100644
--- a/src/Internal/Api/Sync/Api.elm
+++ b/src/Internal/Api/Sync/Api.elm
@@ -22,6 +22,7 @@ type alias SyncInputV1 =
 type alias SyncOutputV1 =
     Task X.Error SO1.Sync
 
+
 type alias SyncOutputV2 =
     Task X.Error SO2.Sync
 
diff --git a/src/Internal/Api/Sync/V2/Upcast.elm b/src/Internal/Api/Sync/V2/Upcast.elm
index 96516a7..a85066d 100644
--- a/src/Internal/Api/Sync/V2/Upcast.elm
+++ b/src/Internal/Api/Sync/V2/Upcast.elm
@@ -4,6 +4,7 @@ import Dict
 import Internal.Api.Sync.V1.SpecObjects as PO
 import Internal.Api.Sync.V2.SpecObjects as SO
 
+
 upcastSync : PO.Sync -> SO.Sync
 upcastSync old =
     { accountData = old.accountData
@@ -12,6 +13,7 @@ upcastSync old =
     , rooms = Maybe.map upcastRooms old.rooms
     }
 
+
 upcastRooms : PO.Rooms -> SO.Rooms
 upcastRooms old =
     { invite = old.invite
@@ -20,6 +22,7 @@ upcastRooms old =
     , leave = Dict.map (\_ -> upcastLeftRoom) old.leave
     }
 
+
 upcastJoinedRoom : PO.JoinedRoom -> SO.JoinedRoom
 upcastJoinedRoom old =
     { accountData = old.accountData
@@ -31,10 +34,12 @@ upcastJoinedRoom old =
     , unreadThreadNotifications = Dict.empty
     }
 
+
 upcastState : PO.State -> SO.State
 upcastState old =
     { events = List.map upcastClientEventWithoutRoomId old.events }
 
+
 upcastClientEventWithoutRoomId : PO.ClientEventWithoutRoomId -> SO.ClientEventWithoutRoomId
 upcastClientEventWithoutRoomId old =
     { content = old.content
@@ -46,6 +51,7 @@ upcastClientEventWithoutRoomId old =
     , unsigned = Maybe.map upcastUnsigned old.unsigned
     }
 
+
 upcastUnsigned : PO.UnsignedData -> SO.UnsignedData
 upcastUnsigned (PO.UnsignedData old) =
     SO.UnsignedData
@@ -55,6 +61,7 @@ upcastUnsigned (PO.UnsignedData old) =
         , transactionId = old.transactionId
         }
 
+
 upcastTimeline : PO.Timeline -> SO.Timeline
 upcastTimeline old =
     { events = List.map upcastClientEventWithoutRoomId old.events
@@ -62,6 +69,7 @@ upcastTimeline old =
     , prevBatch = old.prevBatch
     }
 
+
 upcastLeftRoom : PO.LeftRoom -> SO.LeftRoom
 upcastLeftRoom old =
     { accountData = old.accountData
diff --git a/src/Internal/Values/Credentials.elm b/src/Internal/Values/Credentials.elm
index b78827a..68d0973 100644
--- a/src/Internal/Values/Credentials.elm
+++ b/src/Internal/Values/Credentials.elm
@@ -1,5 +1,9 @@
 module Internal.Values.Credentials exposing (..)
 
+{-| The Credentials type is the keychain of the Matrix SDK.
+It handles all communication with the homeserver.
+-}
+
 import Internal.Tools.Hashdict as Hashdict exposing (Hashdict)
 import Internal.Values.Room as Room exposing (Room)
 
@@ -14,6 +18,23 @@ type AccessToken
     | UsernameAndPassword { username : String, password : String, accessToken : Maybe String }
 
 
+{-| Get the access token the Credentials type is using, if any.
+-}
+getAccessToken : Credentials -> Maybe String
+getAccessToken (Credentials { access }) =
+    case access of
+        AccessToken s ->
+            Just s
+
+        NoAccess ->
+            Nothing
+
+        UsernameAndPassword { accessToken } ->
+            accessToken
+
+
+{-| Internal value to be used as a "default" for credentials settings.
+-}
 defaultCredentials : String -> Credentials
 defaultCredentials homeserver =
     Credentials
@@ -23,6 +44,8 @@ defaultCredentials homeserver =
         }
 
 
+{-| Create a Credentials type using an unknown access token.
+-}
 fromAccessToken : { accessToken : String, homeserver : String } -> Credentials
 fromAccessToken { accessToken, homeserver } =
     case defaultCredentials homeserver of
@@ -30,6 +53,8 @@ fromAccessToken { accessToken, homeserver } =
             Credentials { c | access = AccessToken accessToken }
 
 
+{-| Create a Credentials type using a username and password.
+-}
 fromLoginCredentials : { username : String, password : String, homeserver : String } -> Credentials
 fromLoginCredentials { username, password, homeserver } =
     case defaultCredentials homeserver of
@@ -37,11 +62,18 @@ fromLoginCredentials { username, password, homeserver } =
             Credentials { c | access = UsernameAndPassword { username = username, password = password, accessToken = Nothing } }
 
 
+{-| Get a room from the Credentials type by the room's id.
+-}
 getRoomById : String -> Credentials -> Maybe Room
 getRoomById roomId (Credentials cred) =
     Hashdict.get roomId cred.rooms
 
 
+{-| Add a new room to the Credentials type. If a room with this id already exists, it is overwritten.
+
+This function can hence also be used as an update function for rooms.
+
+-}
 insertRoom : Room -> Credentials -> Credentials
 insertRoom room (Credentials cred) =
     Credentials