From df12d5108ddade171e851fd9618e0da25c8dc788 Mon Sep 17 00:00:00 2001
From: Juan Cruz Viotti <juanchiviotti@gmail.com>
Date: Fri, 5 Dec 2014 13:49:33 -0400
Subject: [PATCH] Document resin/auth

---
 lib/resin/auth/auth.coffee | 91 +++++++++++++++++++++++++++++++++++---
 1 file changed, 85 insertions(+), 6 deletions(-)

diff --git a/lib/resin/auth/auth.coffee b/lib/resin/auth/auth.coffee
index bbcac0a0..1e05adfe 100644
--- a/lib/resin/auth/auth.coffee
+++ b/lib/resin/auth/auth.coffee
@@ -6,10 +6,42 @@ server = require('../server/server')
 errors = require('../errors/errors')
 settings = require('../settings')
 
+# Authenticate with the server
+#
+# @private
+#
+# @param {Object} credentials in the form of username, password
+# @option credentials {String} username the username
+# @option credentials {String} password user password
+# @param {Function} callback (error, token)
+#
+# @note You should use login() when possible, as it takes care of saving the token as well.
+#
+# @example Authenticate
+#		resin.auth.authenticate credentials, (error, token) ->
+#			throw error if error?
+#			console.log(token)
+#
 exports.authenticate = (credentials, callback) ->
 	server.post settings.get('urls.authenticate'), credentials, (error, response) ->
 		return callback(error, response?.body)
 
+# Login to Resin.io
+#
+# Is the login is successful, the token is persisted between sessions.
+#
+# @param {Object} credentials in the form of username, password
+# @option credentials {String} username the username
+# @option credentials {String} password user password
+# @param {Function} callback (error)
+#
+# @note This function saves the token to the directory configured in dataPrefix
+#
+# @example Login to Resin.io
+#		resin.auth.login credentials, (error) ->
+#			throw error if error?
+#			console.log('I\'m logged in!')
+#
 exports.login = (credentials, callback) ->
 	async.waterfall([
 
@@ -21,14 +53,61 @@ exports.login = (credentials, callback) ->
 
 	], callback)
 
-# Handy aliases
-exports.isLoggedIn = token.hasToken
-exports.getToken = token.getToken
+# Check if you're logged in
+#
+# @param {Function} callback (isLoggedIn)
+#
+# @example Check if logged in
+#		resin.auth.isLoggedIn (isLoggedIn) ->
+#			if isLoggedIn
+#				console.log('I\'m in!')
+#			else
+#				console.log('Too bad!')
+#
+exports.isLoggedIn = (callback) ->
+	token.hasToken(callback)
 
-# TODO: Maybe we should post to /logout or something
-# like that to invalidate the token on the server?
-exports.logout = token.clearToken
+# Get current logged in user's token
+#
+# @param {Function} callback (error, isLoggedIn)
+#
+# @note This function simply delegates to resin.token.getToken() for convenience
+#
+# @example Get curren token
+#		resin.auth.getToken (error, token) ->
+#			throw error if error?
+#			console.log(token)
+#
+exports.getToken = (callback) ->
+	token.getToken(callback)
 
+# Logout from Resin.io
+#
+# @param {Function} callback (error)
+#
+# @example Logout from Resin.io
+#		resin.auth.logout (error) ->
+#			throw error if error?
+#			console.log('I\'m out!')
+#
+# @todo Maybe we should post to /logout or something to invalidate the token on the server?
+#
+exports.logout = (callback) ->
+	token.clearToken(callback)
+
+# Parse colon separated credentials
+#
+# @private
+#
+# @param {String} colon separated credentials (username:password)
+# @param {Function} callback (error, credentials)
+#
+#	@example Parse credentials
+#		resin.auth.parseCredentials 'johndoe:secret', (error, credentials) ->
+#			throw error if error?
+#			console.log(credentials.username)
+#			console.log(credentials.password)
+#
 exports.parseCredentials = (credentials, callback) ->
 	result = credentials.split(':')