From 9f643fee7a3e9373b64176808c63521bf1b051c1 Mon Sep 17 00:00:00 2001
From: "diamondburned (Forefront)" <datutbrus@gmail.com>
Date: Tue, 14 Jan 2020 20:56:50 -0800
Subject: [PATCH] Minor fixes, package synopsis

---
 api/api.go          |  2 ++
 discord/discord.go  |  4 ++++
 gateway/gateway.go  | 22 ++++++++++++++++------
 gateway/sequence.go |  8 ++++----
 httputil/client.go  |  2 ++
 json/json.go        |  2 ++
 wsutil/ws.go        |  2 ++
 7 files changed, 32 insertions(+), 10 deletions(-)
 create mode 100644 discord/discord.go

diff --git a/api/api.go b/api/api.go
index 301a2c5..f57cf65 100644
--- a/api/api.go
+++ b/api/api.go
@@ -1,3 +1,5 @@
+// Package api provides an interface to interact with the Discord REST API. It
+// handles rate limiting, as well as authorizing and more.
 package api
 
 import (
diff --git a/discord/discord.go b/discord/discord.go
new file mode 100644
index 0000000..767fd81
--- /dev/null
+++ b/discord/discord.go
@@ -0,0 +1,4 @@
+// Package discord provides common structures that the whole repository uses. It
+// does not (and should not) contain API-specific structures, or WS-specific
+// structures.
+package discord
diff --git a/gateway/gateway.go b/gateway/gateway.go
index 0e9b40a..31fec58 100644
--- a/gateway/gateway.go
+++ b/gateway/gateway.go
@@ -1,3 +1,10 @@
+// Package gateway handles the Discord gateway (or Websocket) connection, its
+// events, and everything related to it. This includes logging into the
+// Websocket.
+//
+// This package does not abstract events and function handlers; instead, it
+// leaves that to the session package. This package exposes only a single Events
+// channel.
 package gateway
 
 import (
@@ -62,10 +69,11 @@ type Gateway struct {
 	// Retries on connect and reconnect.
 	WSRetries uint // 3
 
-	Events    chan Event
-	SessionID string
+	// All events sent over are pointers to Event structs (structs suffixed with
+	// "Event")
+	Events chan Event
 
-	URL string // URL
+	SessionID string
 
 	Identity  *IdentifyData
 	Pacemaker *Pacemaker
@@ -76,7 +84,7 @@ type Gateway struct {
 	// Only use for debugging
 
 	// If this channel is non-nil, all incoming OP packets will also be sent
-	// here.
+	// here. This should be buffered, so to not block the main loop.
 	OP chan Event
 
 	// Filled by methods, internal use
@@ -98,10 +106,9 @@ func NewGatewayWithDriver(token string, driver json.Driver) (*Gateway, error) {
 	}
 
 	g := &Gateway{
-		URL:       URL,
 		Driver:    driver,
 		WSTimeout: WSTimeout,
-		Events:    make(chan Event),
+		Events:    make(chan Event, WSBuffer),
 		Identity: &IdentifyData{
 			Token:             token,
 			Properties:        Identity,
@@ -191,6 +198,8 @@ func (g *Gateway) Start() error {
 		if err := AssertEvent(g, <-ch, DispatchOP, &ready); err != nil {
 			return errors.Wrap(err, "Error at Ready")
 		}
+		g.Events <- &ready
+
 	} else {
 		if err := g.Resume(); err != nil {
 			return errors.Wrap(err, "Failed to resume")
@@ -201,6 +210,7 @@ func (g *Gateway) Start() error {
 		if err := AssertEvent(g, <-ch, DispatchOP, &resumed); err != nil {
 			return errors.Wrap(err, "Error at Resumed")
 		}
+		g.Events <- &resumed
 	}
 
 	// Start the event handler
diff --git a/gateway/sequence.go b/gateway/sequence.go
index 7f1a9a3..15e66d8 100644
--- a/gateway/sequence.go
+++ b/gateway/sequence.go
@@ -3,12 +3,12 @@ package gateway
 import "sync/atomic"
 
 type Sequence struct {
-	seq *int64
+	seq int64
 }
 
 func NewSequence() Sequence {
-	return Sequence{new(int64)}
+	return Sequence{0}
 }
 
-func (s *Sequence) Set(seq int64) { atomic.StoreInt64(s.seq, seq) }
-func (s *Sequence) Get() int64    { return atomic.LoadInt64(s.seq) }
+func (s *Sequence) Set(seq int64) { atomic.StoreInt64(&s.seq, seq) }
+func (s *Sequence) Get() int64    { return atomic.LoadInt64(&s.seq) }
diff --git a/httputil/client.go b/httputil/client.go
index d88dc80..ee09186 100644
--- a/httputil/client.go
+++ b/httputil/client.go
@@ -1,3 +1,5 @@
+// Package httputil provides abstractions around the common needs of HTTP. It
+// also allows swapping in and out the HTTP client.
 package httputil
 
 import (
diff --git a/json/json.go b/json/json.go
index a97623a..a0941c9 100644
--- a/json/json.go
+++ b/json/json.go
@@ -1,3 +1,5 @@
+// Package json allows for different implementations of JSON serializing, as
+// well as extra optional types needed.
 package json
 
 import (
diff --git a/wsutil/ws.go b/wsutil/ws.go
index 31c0da0..cf1181a 100644
--- a/wsutil/ws.go
+++ b/wsutil/ws.go
@@ -1,3 +1,5 @@
+// Package wsutil provides abstractions around the Websocket, including rate
+// limits.
 package wsutil
 
 import (