From 96973a17b3e2301bb3d9f3b1d3f3c1b80f918fb1 Mon Sep 17 00:00:00 2001
From: Kevin Chabowski <kevin@kch42.de>
Date: Tue, 25 Mar 2014 16:04:45 +0100
Subject: Documenting the new chat package. Also fixing access rights

---
 chat/buddy.go    | 10 +++++++---
 chat/messages.go |  2 ++
 chat/rooms.go    | 48 ++++++++++++++++++++++++++----------------------
 3 files changed, 35 insertions(+), 25 deletions(-)

diff --git a/chat/buddy.go b/chat/buddy.go
index c6f07ad..5b2308c 100644
--- a/chat/buddy.go
+++ b/chat/buddy.go
@@ -4,13 +4,15 @@ import (
 	"time"
 )
 
+// Buddy represents a user that participates in a chat.
+// Read from the Receive channel to get incoming messages
 type Buddy struct {
 	Nick    string
 	Receive chan Message
 	room    *Room
 }
 
-func NewBuddy(nick string, room *Room) *Buddy {
+func newBuddy(nick string, room *Room) *Buddy {
 	return &Buddy{
 		Nick:    nick,
 		Receive: make(chan Message),
@@ -18,10 +20,12 @@ func NewBuddy(nick string, room *Room) *Buddy {
 	}
 }
 
+// Leave will remove the buddy from the room.
 func (b *Buddy) Leave() {
-	b.room.Leave(b.Nick)
+	b.room.leave(b.Nick)
 }
 
+// Push pushes a message to the buddies Receive channel
 func (b *Buddy) Push(msg Message) {
 	go func() {
 		select {
@@ -33,7 +37,7 @@ func (b *Buddy) Push(msg Message) {
 
 // Say sends a text as a chat message of this user to the connected room.
 func (b *Buddy) Say(text string) {
-	b.room.Messages <- Message{
+	b.room.messages <- Message{
 		Type: MsgChat,
 		User: b.Nick,
 		Text: text,
diff --git a/chat/messages.go b/chat/messages.go
index 793fc6c..f03eae0 100644
--- a/chat/messages.go
+++ b/chat/messages.go
@@ -5,6 +5,7 @@ import (
 	"errors"
 )
 
+// MsgType describes the purpose of a message
 type MsgType int
 
 const (
@@ -26,6 +27,7 @@ func (mt *MsgType) MarshalJSON() ([]byte, error) {
 	return nil, errors.New("Unknown message type")
 }
 
+// Message represents a message that can be sent to a buddy. The Text field has no meaning, if Type != MsgChat.
 type Message struct {
 	Type MsgType `json:"type"`
 	User string  `json:"user"`
diff --git a/chat/rooms.go b/chat/rooms.go
index e954e29..1fb831a 100644
--- a/chat/rooms.go
+++ b/chat/rooms.go
@@ -4,45 +4,47 @@ import (
 	"errors"
 )
 
+// Room represents a chatroom.
 type Room struct {
-	Messages chan Message
-	Buddies  map[string]*Buddy
+	messages chan Message
+	buddies  map[string]*Buddy
 }
 
-func NewRoom() (r *Room) {
+func newRoom() (r *Room) {
 	r = new(Room)
-	r.Messages = make(chan Message)
-	r.Buddies = make(map[string]*Buddy)
-	go r.Broadcast()
+	r.messages = make(chan Message)
+	r.buddies = make(map[string]*Buddy)
+	go r.broadcast()
 	return
 }
 
-func (r *Room) Leave(nick string) {
-	if _, ok := r.Buddies[nick]; !ok {
+func (r *Room) leave(nick string) {
+	if _, ok := r.buddies[nick]; !ok {
 		return
 	}
 
-	delete(r.Buddies, nick)
-	if len(r.Buddies) == 0 {
-		close(r.Messages)
+	delete(r.buddies, nick)
+	if len(r.buddies) == 0 {
+		close(r.messages)
 	} else {
-		r.Messages <- Message{
+		r.messages <- Message{
 			Type: MsgLeave,
 			User: nick,
 		}
 	}
 }
 
-func (r *Room) Broadcast() {
-	for m := range r.Messages {
-		for _, buddy := range r.Buddies {
+func (r *Room) broadcast() {
+	for m := range r.messages {
+		for _, buddy := range r.buddies {
 			buddy.Push(m)
 		}
 	}
 }
 
+// ListBuddies returns a list of nicknames of the connected buddies.
 func (r *Room) ListBuddies() (buddies []string) {
-	for nick := range r.Buddies {
+	for nick := range r.buddies {
 		buddies = append(buddies, nick)
 	}
 	return
@@ -53,32 +55,34 @@ var (
 	perroom int
 )
 
+// InitRooms initializes the internal rooms variable. Use this, before calling Join.
 func InitRooms(room_limit int) {
 	rooms = make(map[string]*Room)
 	perroom = room_limit
 }
 
+// Join joins a buddy to a room. The room will be created, if it doesn't exist.
 func Join(room, nick string) (*Buddy, *Room, error) {
 	r, ok := rooms[room]
 	if !ok {
-		r = NewRoom()
+		r = newRoom()
 		rooms[room] = r
 	}
 
-	if _, there := r.Buddies[nick]; there {
+	if _, there := r.buddies[nick]; there {
 		return nil, nil, errors.New("Nickname is already in use")
 	}
 
-	if len(r.Buddies) >= perroom {
+	if len(r.buddies) >= perroom {
 		return nil, nil, errors.New("Room is full")
 	}
 
-	r.Messages <- Message{
+	r.messages <- Message{
 		Type: MsgJoin,
 		User: nick,
 	}
 
-	b := NewBuddy(nick, r)
-	r.Buddies[nick] = b
+	b := newBuddy(nick, r)
+	r.buddies[nick] = b
 	return b, r, nil
 }
-- 
cgit v1.2.3-54-g00ecf