From 29afebdb60a57a64be219fe9d1a35b45a94c5efc Mon Sep 17 00:00:00 2001
From: warrenbuckley <wbuckley@thecogworks.co.uk>
Date: Tue, 26 Aug 2014 15:08:40 +0100
Subject: [PATCH] Initial starting work on ng-doc fleshing out for
 auth.resource.js (Also to see if Core team happy with this before investing
 too much time)

---
 .../src/common/resources/auth.resource.js     | 113 ++++++++++++++++--
 1 file changed, 103 insertions(+), 10 deletions(-)

diff --git a/src/Umbraco.Web.UI.Client/src/common/resources/auth.resource.js b/src/Umbraco.Web.UI.Client/src/common/resources/auth.resource.js
index 7f214400d5..e83b35e087 100644
--- a/src/Umbraco.Web.UI.Client/src/common/resources/auth.resource.js
+++ b/src/Umbraco.Web.UI.Client/src/common/resources/auth.resource.js
@@ -1,14 +1,38 @@
 /**
-    * @ngdoc service
-    * @name umbraco.resources.authResource
-    * @description Loads in data for authentication
-**/
+ * @ngdoc service
+ * @name umbraco.resources.authResource
+ * @description
+ * This Resource perfomrs actions to common authentication tasks for the Umbraco backoffice user
+ *
+ * @requires $q 
+ * @requires $http
+ * @requires umbRequestHelper
+ * @requires angularHelper
+ */
 function authResource($q, $http, umbRequestHelper, angularHelper) {
 
     return {
-        //currentUser: currentUser,
 
-        /** Logs the user in if the credentials are good */
+        /**
+         * @ngdoc method
+         * @name umbraco.resources.authResource#performLogin
+         * @methodOf umbraco.resources.authResource
+         *
+         * @description
+         * Logs the Umbraco backoffice user in if the credentials are good
+         *
+         * ##usage
+         * <pre>
+         * authResource.performLogin(login, password)
+         *    .then(function(data) {
+         *        //Do stuff for login...
+         *    });
+         * </pre> 
+         * @param {string} login Username of backoffice user
+         * @param {string} password Password of backoffice user
+         * @returns {Promise} resourcePromise object
+         *
+         */
         performLogin: function (username, password) {
             
             if (!username || !password) {
@@ -28,6 +52,24 @@ function authResource($q, $http, umbRequestHelper, angularHelper) {
                 'Login failed for user ' + username);
         },
         
+        /**
+         * @ngdoc method
+         * @name umbraco.resources.authResource#performLogout
+         * @methodOf umbraco.resources.authResource
+         *
+         * @description
+         * Logs out the Umbraco backoffice user
+         *
+         * ##usage
+         * <pre>
+         * authResource.performLogout()
+         *    .then(function(data) {
+         *        //Do stuff for logging out...
+         *    });
+         * </pre>
+         * @returns {Promise} resourcePromise object
+         *
+         */
         performLogout: function() {
             return umbRequestHelper.resourcePromise(
                 $http.post(
@@ -36,7 +78,24 @@ function authResource($q, $http, umbRequestHelper, angularHelper) {
                         "PostLogout")));
         },
         
-        /** Sends a request to the server to get the current user details, will return a 401 if the user is not logged in  */
+        /**
+         * @ngdoc method
+         * @name umbraco.resources.authResource#getCurrentUser
+         * @methodOf umbraco.resources.authResource
+         *
+         * @description
+         * Sends a request to the server to get the current user details, will return a 401 if the user is not logged in
+         *
+         * ##usage
+         * <pre>
+         * authResource.getCurrentUser()
+         *    .then(function(data) {
+         *        //Do stuff for fetching the current logged in Umbraco backoffice user
+         *    });
+         * </pre>
+         * @returns {Promise} resourcePromise object
+         *
+         */
         getCurrentUser: function () {
             
             return umbRequestHelper.resourcePromise(
@@ -47,7 +106,24 @@ function authResource($q, $http, umbRequestHelper, angularHelper) {
                 'Server call failed for getting current user'); 
         },
         
-        /** Checks if the user is logged in or not - does not return 401 or 403 */
+        /**
+         * @ngdoc method
+         * @name umbraco.resources.authResource#isAuthenticated
+         * @methodOf umbraco.resources.authResource
+         *
+         * @description
+         * Checks if the user is logged in or not - does not return 401 or 403
+         *
+         * ##usage
+         * <pre>
+         * authResource.isAuthenticated()
+         *    .then(function(data) {
+         *        //Do stuff to check if user is authenticated
+         *    });
+         * </pre>
+         * @returns {Promise} resourcePromise object
+         *
+         */
         isAuthenticated: function () {
 
             return umbRequestHelper.resourcePromise(
@@ -72,8 +148,25 @@ function authResource($q, $http, umbRequestHelper, angularHelper) {
                     }
                 });
         },
-        
-        /** Gets the user's remaining seconds before their login times out */
+
+        /**
+         * @ngdoc method
+         * @name umbraco.resources.authResource#getRemainingTimeoutSeconds
+         * @methodOf umbraco.resources.authResource
+         *
+         * @description
+         * Gets the user's remaining seconds before their login times out
+         *
+         * ##usage
+         * <pre>
+         * authResource.getRemainingTimeoutSeconds()
+         *    .then(function(data) {
+         *        //Number of seconds is returned
+         *    });
+         * </pre>
+         * @returns {Promise} resourcePromise object
+         *
+         */
         getRemainingTimeoutSeconds: function () {
 
             return umbRequestHelper.resourcePromise(