add documentation to users.resource

src/Umbraco.Web.UI.Client/src/common/resources/users.resource.js

@@ -4,13 +4,33 @@
  * @function
  *
  * @description
- * Used by the users section to get users and send requests to create, invite, delete, etc. users.
+ * Used by the users section to get users and send requests to create, invite, disable, etc. users.
  */
 (function () {
     'use strict';
 
     function usersResource($http, umbRequestHelper, $q, umbDataFormatter) {
 
+        /**
+          * @ngdoc method
+          * @name umbraco.resources.usersResource#clearAvatar
+          * @methodOf umbraco.resources.usersResource
+          *
+          * @description
+          * Deletes the user avatar
+          *
+          * ##usage
+          * <pre>
+          * usersResource.clearAvatar(1)
+          *    .then(function() {
+          *        alert("avatar is gone");
+          *    });
+          * </pre>
+          * 
+          * @param {Array} id id of user.
+          * @returns {Promise} resourcePromise object.
+          *
+          */
         function clearAvatar(userId) {
 
             return umbRequestHelper.resourcePromise(
@@ -22,6 +42,26 @@
                 'Failed to clear the user avatar ' + userId);
         }
 
+        /**
+          * @ngdoc method
+          * @name umbraco.resources.usersResource#disableUsers
+          * @methodOf umbraco.resources.usersResource
+          *
+          * @description
+          * Disables a collection of users
+          *
+          * ##usage
+          * <pre>
+          * usersResource.disableUsers([1, 2, 3, 4, 5])
+          *    .then(function() {
+          *        alert("users were disabled");
+          *    });
+          * </pre>
+          * 
+          * @param {Array} ids ids of users to disable.
+          * @returns {Promise} resourcePromise object.
+          *
+          */
         function disableUsers(userIds) {
             if (!userIds) {
                 throw "userIds not specified";
@@ -39,6 +79,26 @@
                 'Failed to disable the users ' + userIds.join(","));
         }
 
+        /**
+          * @ngdoc method
+          * @name umbraco.resources.usersResource#enableUsers
+          * @methodOf umbraco.resources.usersResource
+          *
+          * @description
+          * Enables a collection of users
+          *
+          * ##usage
+          * <pre>
+          * usersResource.enableUsers([1, 2, 3, 4, 5])
+          *    .then(function() {
+          *        alert("users were enabled");
+          *    });
+          * </pre>
+          * 
+          * @param {Array} ids ids of users to enable.
+          * @returns {Promise} resourcePromise object.
+          *
+          */
         function enableUsers(userIds) {
             if (!userIds) {
                 throw "userIds not specified";
@@ -55,6 +115,26 @@
                 'Failed to enable the users ' + userIds.join(","));
         }
 
+        /**
+          * @ngdoc method
+          * @name umbraco.resources.usersResource#unlockUsers
+          * @methodOf umbraco.resources.usersResource
+          *
+          * @description
+          * Unlocks a collection of users
+          *
+          * ##usage
+          * <pre>
+          * usersResource.unlockUsers([1, 2, 3, 4, 5])
+          *    .then(function() {
+          *        alert("users were unlocked");
+          *    });
+          * </pre>
+          * 
+          * @param {Array} ids ids of users to unlock.
+          * @returns {Promise} resourcePromise object.
+          *
+          */
         function unlockUsers(userIds) {
             if (!userIds) {
                 throw "userIds not specified";
@@ -71,6 +151,27 @@
                 'Failed to enable the users ' + userIds.join(","));
         }
 
+        /**
+          * @ngdoc method
+          * @name umbraco.resources.usersResource#setUserGroupsOnUsers
+          * @methodOf umbraco.resources.usersResource
+          *
+          * @description
+          * Overwrites the existing user groups on a collection of users
+          *
+          * ##usage
+          * <pre>
+          * usersResource.setUserGroupsOnUsers(['admin', 'editor'], [1, 2, 3, 4, 5])
+          *    .then(function() {
+          *        alert("users were updated");
+          *    });
+          * </pre>
+          * 
+          * @param {Array} userGroupAliases aliases of user groups.
+          * @param {Array} ids ids of users to update.
+          * @returns {Promise} resourcePromise object.
+          *
+          */
         function setUserGroupsOnUsers(userGroups, userIds) {
             var userGroupAliases = userGroups.map(function(o) { return o.alias; });
             var query = "userGroupAliases=" + userGroupAliases.join("&userGroupAliases=") + "&userIds=" + userIds.join("&userIds=");
@@ -83,6 +184,34 @@
                 'Failed to set user groups ' + userGroupAliases.join(",") + ' on the users ' + userIds.join(","));
         }
 
+        /**
+          * @ngdoc method
+          * @name umbraco.resources.usersResource#getPagedResults
+          * @methodOf umbraco.resources.usersResource
+          *
+          * @description
+          * Get users
+          *
+          * ##usage
+          * <pre>
+          * usersResource.getPagedResults({pageSize: 10, pageNumber: 2})
+          *    .then(function(data) {
+          *        var users = data.items;
+          *        alert('they are here!');
+          *    });
+          * </pre>
+          * 
+          * @param {Object} options optional options object
+          * @param {Int} options.pageSize if paging data, number of users per page, default = 25
+          * @param {Int} options.pageNumber if paging data, current page index, default = 1
+          * @param {String} options.filter if provided, query will only return those with names matching the filter
+          * @param {String} options.orderDirection can be `Ascending` or `Descending` - Default: `Ascending`
+          * @param {String} options.orderBy property to order users by, default: `Username`
+          * @param {Array} options.userGroups property to filter users by user group
+          * @param {Array} options.userStates property to filter users by user state
+          * @returns {Promise} resourcePromise object containing an array of content items.
+          *
+          */
         function getPagedResults(options) {
             var defaults = {
                 pageSize: 25,
@@ -135,6 +264,26 @@
                 'Failed to retrieve users paged result');
         }
 
+        /**
+          * @ngdoc method
+          * @name umbraco.resources.usersResource#getUser
+          * @methodOf umbraco.resources.usersResource
+          *
+          * @description
+          * Gets a user
+          *
+          * ##usage
+          * <pre>
+          * usersResource.getUser(1)
+          *    .then(function(user) {
+          *        alert("It's here");
+          *    });
+          * </pre>
+          * 
+          * @param {Array} id user id.
+          * @returns {Promise} resourcePromise object containing the user.
+          *
+          */
         function getUser(userId) {
 
             return umbRequestHelper.resourcePromise(
@@ -146,6 +295,26 @@
                 "Failed to retrieve data for user " + userId);
         }
 
+        /**
+          * @ngdoc method
+          * @name umbraco.resources.usersResource#createUser
+          * @methodOf umbraco.resources.usersResource
+          *
+          * @description
+          * Creates a new user
+          *
+          * ##usage
+          * <pre>
+          * usersResource.createUser(user)
+          *    .then(function(newUser) {
+          *        alert("It's here");
+          *    });
+          * </pre>
+          * 
+          * @param {Object} user user to create
+          * @returns {Promise} resourcePromise object containing the new user.
+          *
+          */
         function createUser(user) {
             if (!user) {
                 throw "user not specified";
@@ -163,6 +332,26 @@
                 "Failed to save user");
         }
 
+        /**
+          * @ngdoc method
+          * @name umbraco.resources.usersResource#inviteUser
+          * @methodOf umbraco.resources.usersResource
+          *
+          * @description
+          * Creates and sends an email invitation to a new user
+          *
+          * ##usage
+          * <pre>
+          * usersResource.inviteUser(user)
+          *    .then(function(newUser) {
+          *        alert("It's here");
+          *    });
+          * </pre>
+          * 
+          * @param {Object} user user to invite
+          * @returns {Promise} resourcePromise object containing the new user.
+          *
+          */
         function inviteUser(user) {
             if (!user) {
                 throw "user not specified";
@@ -180,6 +369,26 @@
                 "Failed to invite user");
         }
 
+        /**
+          * @ngdoc method
+          * @name umbraco.resources.usersResource#saveUser
+          * @methodOf umbraco.resources.usersResource
+          *
+          * @description
+          * Saves a user
+          *
+          * ##usage
+          * <pre>
+          * usersResource.saveUser(user)
+          *    .then(function(updatedUser) {
+          *        alert("It's here");
+          *    });
+          * </pre>
+          * 
+          * @param {Object} user object to save
+          * @returns {Promise} resourcePromise object containing the updated user.
+          *
+          */
         function saveUser(user) {
             if (!user) {
                 throw "user not specified";