From 03e9a0d5ac5329a6e74f3e3bf34ef590c863a6d3 Mon Sep 17 00:00:00 2001
From: Tulir Asokan <tulir@maunium.net>
Date: Fri, 23 Mar 2018 14:44:36 +0200
Subject: [PATCH] Documentation and refactoring

---
 gomuks.go                   | 46 ++++++++++++++++++++++++-------------
 interface/gomuks.go         |  5 ++--
 matrix/matrix.go            |  5 ++--
 matrix/pushrules/ruleset.go |  9 ++++++++
 matrix/rooms/member.go      |  1 +
 matrix/rooms/room.go        | 13 ++++++++---
 matrix/sync.go              |  2 +-
 ui/view-login.go            |  2 +-
 ui/view-main.go             |  2 +-
 9 files changed, 58 insertions(+), 27 deletions(-)

diff --git a/gomuks.go b/gomuks.go
index 2dbbdff..0840bfe 100644
--- a/gomuks.go
+++ b/gomuks.go
@@ -22,7 +22,6 @@ import (
 	"path/filepath"
 	"time"
 
-	"maunium.net/go/gomatrix"
 	"maunium.net/go/gomuks/config"
 	"maunium.net/go/gomuks/interface"
 	"maunium.net/go/gomuks/matrix"
@@ -31,6 +30,7 @@ import (
 	"maunium.net/go/tview"
 )
 
+// Gomuks is the wrapper for everything.
 type Gomuks struct {
 	app       *tview.Application
 	ui        *ui.GomuksUI
@@ -41,6 +41,8 @@ type Gomuks struct {
 	stop      chan bool
 }
 
+// NewGomuks creates a new Gomuks instance with everything initialized,
+// but does not start it.
 func NewGomuks(enableDebug bool) *Gomuks {
 	configDir := filepath.Join(os.Getenv("HOME"), ".config/gomuks")
 	gmx := &Gomuks{
@@ -76,16 +78,7 @@ func NewGomuks(enableDebug bool) *Gomuks {
 	return gmx
 }
 
-func (gmx *Gomuks) Stop() {
-	gmx.debug.Print("Disconnecting from Matrix...")
-	gmx.matrix.Stop()
-	gmx.debug.Print("Cleaning up UI...")
-	gmx.app.Stop()
-	gmx.stop <- true
-	gmx.Save()
-	os.Exit(0)
-}
-
+// Save saves the active session and message history.
 func (gmx *Gomuks) Save() {
 	if gmx.config.Session != nil {
 		gmx.debug.Print("Saving session...")
@@ -95,6 +88,8 @@ func (gmx *Gomuks) Save() {
 	gmx.ui.MainView().SaveAllHistory()
 }
 
+// StartAutosave calls Save() every minute until it receives a stop signal
+// on the Gomuks.stop channel.
 func (gmx *Gomuks) StartAutosave() {
 	defer gmx.Recover()
 	ticker := time.NewTicker(time.Minute)
@@ -110,6 +105,21 @@ func (gmx *Gomuks) StartAutosave() {
 	}
 }
 
+// Stop stops the Matrix syncer, the tview app and the autosave goroutine,
+// then saves everything and calls os.Exit(0).
+func (gmx *Gomuks) Stop() {
+	gmx.debug.Print("Disconnecting from Matrix...")
+	gmx.matrix.Stop()
+	gmx.debug.Print("Cleaning up UI...")
+	gmx.app.Stop()
+	gmx.stop <- true
+	gmx.Save()
+	os.Exit(0)
+}
+
+// Recover recovers a panic, closes the tcell screen and either re-panics or
+// shows an user-friendly message about the panic depending on whether or not
+// the debug mode is enabled.
 func (gmx *Gomuks) Recover() {
 	if p := recover(); p != nil {
 		if gmx.App().GetScreen() != nil {
@@ -123,6 +133,10 @@ func (gmx *Gomuks) Recover() {
 	}
 }
 
+// Start opens a goroutine for the autosave loop and starts the tview app.
+//
+// If the tview app returns an error, it will be passed into panic(), which
+// will be recovered as specified in Recover().
 func (gmx *Gomuks) Start() {
 	defer gmx.Recover()
 	go gmx.StartAutosave()
@@ -131,22 +145,22 @@ func (gmx *Gomuks) Start() {
 	}
 }
 
-func (gmx *Gomuks) Matrix() *gomatrix.Client {
-	return gmx.matrix.Client()
-}
-
-func (gmx *Gomuks) MatrixContainer() ifc.MatrixContainer {
+// Matrix returns the MatrixContainer instance.
+func (gmx *Gomuks) Matrix() ifc.MatrixContainer {
 	return gmx.matrix
 }
 
+// App returns the tview Application instance.
 func (gmx *Gomuks) App() *tview.Application {
 	return gmx.app
 }
 
+// Config returns the Gomuks config instance.
 func (gmx *Gomuks) Config() *config.Config {
 	return gmx.config
 }
 
+// UI returns the Gomuks UI instance.
 func (gmx *Gomuks) UI() ifc.GomuksUI {
 	return gmx.ui
 }
diff --git a/interface/gomuks.go b/interface/gomuks.go
index b90aa88..fbe05e1 100644
--- a/interface/gomuks.go
+++ b/interface/gomuks.go
@@ -17,14 +17,13 @@
 package ifc
 
 import (
-	"maunium.net/go/gomatrix"
 	"maunium.net/go/gomuks/config"
 	"maunium.net/go/tview"
 )
 
+// Gomuks is the wrapper for everything.
 type Gomuks interface {
-	Matrix() *gomatrix.Client
-	MatrixContainer() MatrixContainer
+	Matrix() MatrixContainer
 	App() *tview.Application
 	UI() GomuksUI
 	Config() *config.Config
diff --git a/matrix/matrix.go b/matrix/matrix.go
index b062057..8199449 100644
--- a/matrix/matrix.go
+++ b/matrix/matrix.go
@@ -263,9 +263,10 @@ func (c *Container) processOwnMembershipChange(evt *gomatrix.Event) {
 	if membership == prevMembership {
 		return
 	}
-	if membership == "join" {
+	switch membership {
+	case "join":
 		c.ui.MainView().AddRoom(evt.RoomID)
-	} else if membership == "leave" {
+	case "leave":
 		c.ui.MainView().RemoveRoom(evt.RoomID)
 	}
 }
diff --git a/matrix/pushrules/ruleset.go b/matrix/pushrules/ruleset.go
index b533f94..f3026c8 100644
--- a/matrix/pushrules/ruleset.go
+++ b/matrix/pushrules/ruleset.go
@@ -39,6 +39,14 @@ type rawPushRuleset struct {
 	Underride PushRuleArray `json:"underride"`
 }
 
+// UnmarshalJSON parses JSON into this PushRuleset.
+//
+// For override, sender and underride push rule arrays, the type is added
+// to each PushRule and the array is used as-is.
+//
+// For room and sender push rule arrays, the type is added to each PushRule
+// and the array is converted to a map with the rule ID as the key and the
+// PushRule as the value.
 func (rs *PushRuleset) UnmarshalJSON(raw []byte) (err error) {
 	data := rawPushRuleset{}
 	err = json.Unmarshal(raw, &data)
@@ -54,6 +62,7 @@ func (rs *PushRuleset) UnmarshalJSON(raw []byte) (err error) {
 	return
 }
 
+// MarshalJSON is the reverse of UnmarshalJSON()
 func (rs *PushRuleset) MarshalJSON() ([]byte, error) {
 	data := rawPushRuleset{
 		Override:  rs.Override,
diff --git a/matrix/rooms/member.go b/matrix/rooms/member.go
index 20c994b..8fd84e9 100644
--- a/matrix/rooms/member.go
+++ b/matrix/rooms/member.go
@@ -20,6 +20,7 @@ import (
 	"maunium.net/go/gomatrix"
 )
 
+// Membership is an enum specifying the membership state of a room member.
 type Membership string
 
 // The allowed membership states as specified in spec section 10.5.5.
diff --git a/matrix/rooms/room.go b/matrix/rooms/room.go
index 56614de..c24b6db 100644
--- a/matrix/rooms/room.go
+++ b/matrix/rooms/room.go
@@ -34,17 +34,22 @@ type Room struct {
 	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.
+	// 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.
+	// 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
 
-	// fetchHistoryLock is used to make sure multiple goroutines don't fetch history for this room at the same time.
+	// fetchHistoryLock is used to make sure multiple goroutines don't fetch
+	// history for this room at the same time.
 	fetchHistoryLock *sync.Mutex
 }
 
+// LockHistory locks the history fetching mutex.
+// If the mutex is nil, it will be created.
 func (room *Room) LockHistory() {
 	if room.fetchHistoryLock == nil {
 		room.fetchHistoryLock = &sync.Mutex{}
@@ -52,6 +57,8 @@ func (room *Room) LockHistory() {
 	room.fetchHistoryLock.Lock()
 }
 
+// UnlockHistory unlocks the history fetching mutex.
+// If the mutex is nil, this does nothing.
 func (room *Room) UnlockHistory() {
 	if room.fetchHistoryLock != nil {
 		room.fetchHistoryLock.Unlock()
diff --git a/matrix/sync.go b/matrix/sync.go
index a5f3b91..f78359c 100644
--- a/matrix/sync.go
+++ b/matrix/sync.go
@@ -49,7 +49,7 @@ func (s *GomuksSyncer) ProcessResponse(res *gomatrix.RespSync, since string) (er
 	if len(since) == 0 {
 		return
 	}
-	// gdebug.Print("Processing sync response", since, res)
+	// debug.Print("Processing sync response", since, res)
 
 	defer func() {
 		if r := recover(); r != nil {
diff --git a/ui/view-login.go b/ui/view-login.go
index 0707b2d..ff0e44e 100644
--- a/ui/view-login.go
+++ b/ui/view-login.go
@@ -44,7 +44,7 @@ func (ui *GomuksUI) NewLoginView() tview.Primitive {
 		username:   widget.NewAdvancedInputField(),
 		password:   widget.NewAdvancedInputField(),
 
-		matrix: ui.gmx.MatrixContainer(),
+		matrix: ui.gmx.Matrix(),
 		config: ui.gmx.Config(),
 		parent: ui,
 	}
diff --git a/ui/view-main.go b/ui/view-main.go
index dc86ad5..1f14943 100644
--- a/ui/view-main.go
+++ b/ui/view-main.go
@@ -56,7 +56,7 @@ func (ui *GomuksUI) NewMainView() tview.Primitive {
 		roomView: tview.NewPages(),
 		rooms:    make(map[string]*widget.RoomView),
 
-		matrix: ui.gmx.MatrixContainer(),
+		matrix: ui.gmx.Matrix(),
 		gmx:    ui.gmx,
 		config: ui.gmx.Config(),
 		parent: ui,