Slightly improved comments

README.md

@@ -1,5 +1,5 @@
 # Discordgo
-Golang DiscordApp API.
+Golang Discord API.
 
 This is my first Golang project and it is <del>probably</del> not even suitable for use :)
 Everything here so far is likely to change as I learn Golang better and refine the API names and such.
@@ -12,7 +12,7 @@ If you're looking for a functional Discord API for Golang check out https://gith
 
 
 
-# Other DiscordApp APIs
+# Other Discord APIs
 - [go-discord](https://github.com/gdraynz/go-discord)
 - [discord-go](https://github.com/Xackery/discord)
 - [discord.py](https://github.com/Rapptz/discord.py)

discord.go

@@ -1,6 +1,6 @@
 /******************************************************************************
  * Discordgo v0 by Bruce Marriner <bruce@sqls.net>
- * A DiscordApp API for Golang.
+ * A Discord API for Golang.
  *
  * Currently only the REST API is functional.  I will add on the websocket
  * layer once I get the API section where I want it.
@@ -9,7 +9,8 @@
 
 package discordgo
 
-// Define known API URL paths as global constants
+// These will absolutely change.  I already don't like them.
+// Constants that define the different Discord API URLs.
 const (
 	discordUrl = "http://discordapp.com"
 	discordApi = discordUrl + "/api/"
@@ -18,18 +19,17 @@ const (
 	users      = discordApi + "users"
 )
 
-// possible all-inclusive strut..
+// A Discord structure represents a all-inclusive (hopefully) structure to
+// access the Discord REST API for a given authenticated user.
 type Discord struct {
-	Session
+	Session Session
 	User    User
 	Servers []Server
 }
 
-// Create a new connection to Discord API.  Returns a client session handle.
-// this is a all inclusive type of easy setup command that will return
-// a connection, user information, and available channels.
-// This is probably the most common way to use the library but you
-// can use the "manual" functions below instead.
+// New creates a new connection to Discord and returns a Discord structure.
+// This provides an easy entry where most commonly needed information is
+// automatically fetched.
 func New(email string, password string) (discord *Discord, err error) {
 
 	session := Session{}
@@ -50,3 +50,15 @@ func New(email string, password string) (discord *Discord, err error) {
 
 	return
 }
+
+// Renew essentially reruns the New command without creating a new session.
+// This will update all the user, server, and channel information that was
+// fetched with the New command.  This is not an efficient way of doing this
+// but if used infrequently it does provide convenience.
+func (discord Discord) Renew() (err error) {
+
+	discord.User, err = discord.Session.Self()
+	discord.Servers, err = discord.Session.Servers()
+
+	return
+}

session.go

@@ -1,10 +1,6 @@
 /******************************************************************************
- * Discordgo v0 by Bruce Marriner <bruce@sqls.net>
- * A DiscordApp API for Golang.
- *
- * Currently only the REST API is functional.  I will add on the websocket
- * layer once I get the API section where I want it.
- *
+ * Discordgo by Bruce Marriner <bruce@sqls.net>
+ * A Discord API for Golang.
  */
 
 package discordgo
@@ -19,14 +15,15 @@ import (
 	"time"
 )
 
-// Represents a session connection to the Discord REST API.
-// I suspect I'll be adding more to this later :)
+// A Session represents a connection to the Discord REST API.
+// Token : The authentication token returned from Discord
+// Debug : If set to ture debug logging will be displayed.
 type Session struct {
 	Token string
 	Debug bool
 }
 
-// RequestToken asks the Rest server for a token by provided email/password
+// RequestToken asks the Discord server for an authentication token
 func (session *Session) RequestToken(email string, password string) (token string, err error) {
 
 	var urlStr string = fmt.Sprintf("%s/%s", discordApi, "auth/login")
@@ -65,7 +62,7 @@ func (session *Session) RequestToken(email string, password string) (token strin
 	return
 }
 
-// Identify session user
+// Self returns a User structure of the session authenticated user.
 func (session *Session) Self() (user User, err error) {
 
 	body, err := Request(session, fmt.Sprintf("%s/%s", discordApi, "users/@me"))
@@ -74,9 +71,7 @@ func (session *Session) Self() (user User, err error) {
 	return
 }
 
-// Request makes a API GET Request.  This is a general purpose function
-// and is used by all API functions.  It is exposed currently so it can
-// also be used outside of this library.
+// Request makes a REST API GET Request with Discord.
 func Request(session *Session, urlStr string) (body []byte, err error) {
 
 	req, err := http.NewRequest("GET", urlStr, bytes.NewBuffer([]byte(fmt.Sprintf(``))))
@@ -115,7 +110,8 @@ func Request(session *Session, urlStr string) (body []byte, err error) {
 	return
 }
 
-// Get all of the session user's private channels.
+// PrivateChannels returns an array of Channel structures for all private
+// channels of the session authenticated user.
 func (session *Session) PrivateChannels() (channels []Channel, err error) {
 
 	body, err := Request(session, fmt.Sprintf("%s/%s", discordApi, fmt.Sprintf("users/@me/channels")))
@@ -124,7 +120,8 @@ func (session *Session) PrivateChannels() (channels []Channel, err error) {
 	return
 }
 
-// Get all of the session user's servers
+// Servers returns an array of Server structures for all servers for the
+// session authenticated user.
 func (session *Session) Servers() (servers []Server, err error) {
 
 	body, err := Request(session, fmt.Sprintf("%s/%s", discordApi, fmt.Sprintf("users/@me/guilds")))
@@ -133,7 +130,8 @@ func (session *Session) Servers() (servers []Server, err error) {
 	return
 }
 
-// Get all channels for the given server
+// Channels returns an array of Channel structures for all channels of a given
+// server.
 func (session *Session) Channels(serverId int) (channels []Channel, err error) {
 
 	body, err := Request(session, fmt.Sprintf("%s/%s", discordApi, fmt.Sprintf("guilds/%d/channels", serverId)))