doc updates

Author: jakecoffman

README.md

@@ -1,18 +1,19 @@
 # guac
 
-Guacamole client in Go.
+A Guacamole client in Go.
 
 [![GoDoc](https://godoc.org/github.com/wwt/guac?status.svg)](http://godoc.org/github.com/wwt/guac)
 
 ## To run
+## Development
 
 First start guacd in a container, for example:
 
 ```sh
 docker run --name guacd -d -p 4822:4822 guacamole/guacd
 ```
 
-Next, clone this repo and run provided main:
+Next run provided main:
 
 ```sh
 cd guac/cmd/guac
@@ -21,8 +22,9 @@ go run guac.go
 
 Now you can connect with an example UI (coming soon)
 
-## Acknowledgement
+## Acknowledgements
 
-Initially forked from https://github.com/johnzhd/guacamole_client_go which is a direct rewrite of the Java Guacamole client. 
+Initially forked from https://github.com/johnzhd/guacamole_client_go which is a direct rewrite of the Java Guacamole
+client. This project no longer resembles that one but it helped it get off the ground!
 
-This project no longer resembles that one but it helped it get off the ground!
+Some of the comments are taken directly from the official Apache Guacamole Java client.

cmd/guac/guac.go

@@ -68,7 +68,6 @@ func main() {
 // DemoDoConnect creates the tunnel to the remote machine (via guacd)
 func DemoDoConnect(request *http.Request) (guac.Tunnel, error) {
 	config := guac.NewGuacamoleConfiguration()
-	info := guac.NewGuacamoleClientInformation()
 
 	query := request.URL.Query()
 	config.Protocol = query.Get("scheme")
@@ -79,20 +78,20 @@ func DemoDoConnect(request *http.Request) (guac.Tunnel, error) {
 
 	var err error
 	if query.Get("width") != "" {
-		info.OptimalScreenHeight, err = strconv.Atoi(query.Get("width"))
-		if err != nil || info.OptimalScreenHeight == 0 {
+		config.OptimalScreenHeight, err = strconv.Atoi(query.Get("width"))
+		if err != nil || config.OptimalScreenHeight == 0 {
 			logrus.Error("Invalid height")
-			info.OptimalScreenHeight = 600
+			config.OptimalScreenHeight = 600
 		}
 	}
 	if query.Get("height") != "" {
-		info.OptimalScreenWidth, err = strconv.Atoi(query.Get("height"))
-		if err != nil || info.OptimalScreenWidth == 0 {
+		config.OptimalScreenWidth, err = strconv.Atoi(query.Get("height"))
+		if err != nil || config.OptimalScreenWidth == 0 {
 			logrus.Error("Invalid width")
-			info.OptimalScreenWidth = 800
+			config.OptimalScreenWidth = 800
 		}
 	}
-	info.AudioMimetypes = []string{"audio/L16", "rate=44100", "channels=2"}
+	config.AudioMimetypes = []string{"audio/L16", "rate=44100", "channels=2"}
 
 	logrus.Debug("Connecting to guacd")
 	addr, err := net.ResolveTCPAddr("tcp", "127.0.0.1:4822")
@@ -109,7 +108,7 @@ func DemoDoConnect(request *http.Request) (guac.Tunnel, error) {
 	if request.URL.Query().Get("uuid") != "" {
 		config.ConnectionID = request.URL.Query().Get("uuid")
 	}
-	err = stream.Handshake(config, info)
+	err = stream.Handshake(config)
 	if err != nil {
 		return nil, err
 	}

config.go

@@ -1,29 +1,32 @@
 package guac
 
+// Config is the data sent to guacd to configure the session during the handshake.
 type Config struct {
+	// ConnectionID is used to reconnect to an existing session, otherwise leave blank for a new session.
 	ConnectionID string
+	// Protocol is the protocol of the connection from guacd to the remote (rdp, ssh, etc).
 	Protocol     string
+	// Parameters are used to configure protocol specific options like sla for rdp or terminal color schemes.
 	Parameters   map[string]string
-}
-
-func NewGuacamoleConfiguration() *Config {
-	return &Config{
-		Parameters: make(map[string]string),
-	}
-}
 
-type ClientInfo struct {
+	// OptimalScreenWidth is the desired width of the screen
 	OptimalScreenWidth  int
+	// OptimalScreenHeight is the desired height of the screen
 	OptimalScreenHeight int
+	// OptimalResolution is the desired resolution of the screen
 	OptimalResolution   int
+	// AudioMimetypes is an array of the supported audio types
 	AudioMimetypes      []string
+	// VideoMimetypes is an array of the supported video types
 	VideoMimetypes      []string
+	// ImageMimetypes is an array of the supported image types
 	ImageMimetypes      []string
 }
 
-// NewGuacamoleClientInformation Construct function
-func NewGuacamoleClientInformation() *ClientInfo {
-	return &ClientInfo{
+// NewGuacamoleConfiguration returns a Config with sane defaults
+func NewGuacamoleConfiguration() *Config {
+	return &Config{
+		Parameters:          map[string]string{},
 		OptimalScreenWidth:  1024,
 		OptimalScreenHeight: 768,
 		OptimalResolution:   96,

doc.go

@@ -0,0 +1,4 @@
+/*
+Package guac implements a HTTP client and a WebSocket client that connects to an Apache Guacamole server.
+ */
+package guac

mem_session.go

@@ -5,23 +5,28 @@ import (
 	"sync"
 )
 
+// MemorySessionStore is a simple in-memory store of connected sessions that is used by
+// the WebsocketServer to store active sessions.
 type MemorySessionStore struct {
 	sync.RWMutex
 	ConnIds map[string]int
 }
 
+// NewMemorySessionStore creates a new store
 func NewMemorySessionStore() *MemorySessionStore {
 	return &MemorySessionStore{
 		ConnIds: map[string]int{},
 	}
 }
 
+// Get returns a connection by uuid
 func (s *MemorySessionStore) Get(id string) int {
 	s.RLock()
 	defer s.RUnlock()
 	return s.ConnIds[id]
 }
 
+// Add inserts a new connection by uuid
 func (s *MemorySessionStore) Add(id string, req *http.Request) {
 	s.Lock()
 	defer s.Unlock()
@@ -35,6 +40,7 @@ func (s *MemorySessionStore) Add(id string, req *http.Request) {
 	return
 }
 
+// Delete removes a connection by uuid
 func (s *MemorySessionStore) Delete(id string, req *http.Request, tunnel Tunnel) {
 	s.Lock()
 	defer s.Unlock()

server.go

@@ -16,9 +16,9 @@ const (
 	uuidLength               = 36
 )
 
-// Server uses HTTP requests to talk to guacd
+// Server uses HTTP requests to talk to guacd (as opposed to WebSockets in ws_server.go)
 type Server struct {
-	tunnels TunnelMap
+	tunnels *TunnelMap
 	connect func(*http.Request) (Tunnel, error)
 }
 
@@ -30,28 +30,19 @@ func NewServer(connect func(r *http.Request) (Tunnel, error)) *Server {
 	}
 }
 
-/**
- * Registers the given tunnel such that future read/write requests to that
- * tunnel will be properly directed.
- */
+// Registers the given tunnel such that future read/write requests to that tunnel will be properly directed.
 func (s *Server) registerTunnel(tunnel Tunnel) {
 	s.tunnels.Put(tunnel.GetUUID(), tunnel)
 	logger.Debugf("Registered tunnel \"%v\".", tunnel.GetUUID())
 }
 
-/**
- * Deregisters the given tunnel such that future read/write requests to
- * that tunnel will be rejected.
- */
+// Deregisters the given tunnel such that future read/write requests to that tunnel will be rejected.
 func (s *Server) deregisterTunnel(tunnel Tunnel) {
 	s.tunnels.Remove(tunnel.GetUUID())
 	logger.Debugf("Deregistered tunnel \"%v\".", tunnel.GetUUID())
 }
 
-/**
- * Returns the tunnel with the given UUID, if it has been registered with
- * registerTunnel() and not yet deregistered with deregisterTunnel().
- */
+// Returns the tunnel with the given UUID.
 func (s *Server) getTunnel(tunnelUUID string) (ret Tunnel, err error) {
 	var ok bool
 	ret, ok = s.tunnels.Get(tunnelUUID)
@@ -91,8 +82,7 @@ func (s *Server) handleTunnelRequestCore(response http.ResponseWriter, request *
 	if len(query) == 0 {
 		return ErrClient.NewError("No query string provided.")
 	}
-	// If connect operation, call doConnect() and return tunnel UUID
-	// in response.
+	// If connect operation, call doConnect() and return tunnel UUID in response.
 	if query == "connect" {
 		tunnel, e := s.connect(request)