 			set    : 's'
 			alias  : 'a'
 
+	# ### record
+	# ----------
+
+	# Record an "event" in Kissmetrics.
+	# http://support.kissmetrics.com/apis/common-methods#record
+	#
+	# `action` (String): Name of the event you're recording. This is
+	#   usually something a person did or something that affects them.
+	#
+	# `properties` (Object) *Optional*: Properties to associate with
+	#   the person's event. Keys will be used as property names and values
+	#   as property values.
+	#
+	# ```
+	# km.record('Signed up', {page: 'home'})
+	# ```
 	record: (action, properties = {}) ->
 		properties._n = action
 		@generateQuery 'record', properties
 
+	# ### set
+	# -------
+
+	# Set a "property" in Kissmetrics.
+	# http://support.kissmetrics.com/apis/common-methods#set
+	#
+	# `properties` (Object): Properties to associate with
+	#   the person's event. Keys will be used as property names and values
+	#   as property values.
+	#
+	# This behaves exactly like the `properties` argument in `record` except
+	# that it is required and that each property has to be sent in its own query.
+	#
+	# ```
+	# km.set({location: 'San Francisco', gender: 'male'})
+	# ```
 	set: (properties) ->
-		# Each property has to be sent in its own query
 		for name, value of properties
 			data       = {}
 			data[name] = value
 			@generateQuery 'set', data
 
+	# ### alias
+	# ---------
+
+	# Alias a person to another "identity" in Kissmetrics.
+	# http://support.kissmetrics.com/apis/common-methods#alias
+	#
+	# `to` (String): A new identifier to map to the `@person` set on
+	# the current instance.
+	#
+	# ```
+	# km.alias('evan+newemail@example.com')
+	# ```
 	alias: (to) ->
 		@generateQuery 'alias', _n: to
 
+
+	# ### generateQuery
+	# ------------------
+
+	# Prepare data to be sent to Kissmetrics by turning it into a URL path
+	# and query string. Once the query is formed, call `record()` to send
+	# it to Kissmetrics.
+	#
+	# * `type` (String): Type of data being sent (`record`, `set` or `alias`).
+	#
+	# * `data` (Object): Specific data being recorded about this person.
 	generateQuery: (type, data) ->
 		data._k = @key
 		data._p = @person

		(new Image()).src = url


class KissmetricsClient
	constructor: (@key, @person) ->
		@host        = 'trk.kissmetrics.com'

# # Kissmetrics JS

# ## Bootstrap
# -------------

# Keep track of what environment we're running in, Node.js or a browser.
# If we're in Node, require the `https` module for our network requests.
# If we're in a browser we'll just use the implicit requests generated by
# `Image`'s `src` property. Kissmetrics responds to API requests with an
# `image/gif` content type, so the browser won't throw up any warnings.
ENV = if typeof exports isnt 'undefined' then 'node' else 'browser'

https = require 'https' if ENV is 'node'


# ## Requests
# ------------

# Generic wrapper for HTTP requests that abstracts the differences between
# requests made in Node and in a browser.
httpRequest = (url) ->
	if ENV is 'node'
		https.get url
