From 9fd67102ad2cca16c092e23ffd928b77ab08d7e0 Mon Sep 17 00:00:00 2001
From: Tulir Asokan <tulir@maunium.net>
Date: Wed, 21 Mar 2018 23:29:58 +0200
Subject: Refactoring and godocs

---
 matrix/room/member.go | 28 ++++++++++++++++++++++------
 matrix/room/room.go   | 17 ++++++++++++-----
 2 files changed, 34 insertions(+), 11 deletions(-)

(limited to 'matrix/room')

diff --git a/matrix/room/member.go b/matrix/room/member.go
index 3b3a30c..4af20a6 100644
--- a/matrix/room/member.go
+++ b/matrix/room/member.go
@@ -20,18 +20,34 @@ import (
 	"maunium.net/go/gomatrix"
 )
 
+type Membership string
+
+// The allowed membership states as specified in spec section 10.5.5.
+const (
+	MembershipJoin   Membership = "join"
+	MembershipLeave  Membership = "leave"
+	MembershipInvite Membership = "invite"
+	MembershipKnock  Membership = "knock"
+)
+
+// Member represents a member in a room.
 type Member struct {
-	UserID      string `json:"-"`
-	Membership  string `json:"membership"`
-	DisplayName string `json:"displayname"`
-	AvatarURL   string `json:"avatar_url"`
+	// The MXID of the member.
+	UserID string `json:"-"`
+	// The membership status. Defaults to leave.
+	Membership  Membership `json:"membership"`
+	// The display name of the user. Defaults to the user ID.
+	DisplayName string     `json:"displayname"`
+	// The avatar URL of the user. Defaults to an empty string.
+	AvatarURL   string     `json:"avatar_url"`
 }
 
+// eventToRoomMember converts a m.room.member state event into a Member object.
 func eventToRoomMember(userID string, event *gomatrix.Event) *Member {
 	if event == nil {
 		return &Member{
 			UserID:     userID,
-			Membership: "leave",
+			Membership: MembershipLeave,
 		}
 	}
 	membership, _ := event.Content["membership"].(string)
@@ -44,7 +60,7 @@ func eventToRoomMember(userID string, event *gomatrix.Event) *Member {
 
 	return &Member{
 		UserID:      userID,
-		Membership:  membership,
+		Membership:  Membership(membership),
 		DisplayName: displayName,
 		AvatarURL:   avatarURL,
 	}
diff --git a/matrix/room/room.go b/matrix/room/room.go
index 92d6c5a..264ee3b 100644
--- a/matrix/room/room.go
+++ b/matrix/room/room.go
@@ -26,11 +26,18 @@ import (
 type Room struct {
 	*gomatrix.Room
 
+	// The first batch of events that has been fetched for this room.
+	// Used for fetching additional history.
 	PrevBatch        string
-	Owner            string
+	// The MXID of the user whose session this room was created for.
+	SessionUserID    string
+	// MXID -> Member cache calculated from membership events.
 	memberCache      map[string]*Member
+	// The first non-SessionUserID member in the room. Calculated at the same time as memberCache.
 	firstMemberCache string
+	// The name of the room. Calculated from the state event name, canonical_alias or alias or the member cache.
 	nameCache        string
+	// The topic of the room. Directly fetched from the m.room.topic state event.
 	topicCache       string
 }
 
@@ -135,7 +142,7 @@ func (room *Room) updateNameFromMembers() {
 }
 
 // updateNameCache updates the room display name based on the room state in the order
-// specified in section 11.2.2.5 of r0.3.0 of the Client-Server API specification.
+// specified in spec section 11.2.2.5.
 func (room *Room) updateNameCache() {
 	if len(room.nameCache) == 0 {
 		room.updateNameFromNameEvent()
@@ -167,7 +174,7 @@ func (room *Room) createMemberCache() map[string]*Member {
 	room.firstMemberCache = ""
 	if events != nil {
 		for userID, event := range events {
-			if len(room.firstMemberCache) == 0 && userID != room.Owner {
+			if len(room.firstMemberCache) == 0 && userID != room.SessionUserID {
 				room.firstMemberCache = userID
 			}
 			member := eventToRoomMember(userID, event)
@@ -204,7 +211,7 @@ func (room *Room) GetMember(userID string) *Member {
 // NewRoom creates a new Room with the given ID
 func NewRoom(roomID, owner string) *Room {
 	return &Room{
-		Room:  gomatrix.NewRoom(roomID),
-		Owner: owner,
+		Room:          gomatrix.NewRoom(roomID),
+		SessionUserID: owner,
 	}
 }
-- 
cgit v1.2.3