Web UI source code annotation

Part of ongoing Web UI documentation effort. Source code is annotated in a way that it can be processed by documentation generator.

1 files changed, 647 insertions, 28 deletions

diff --git a/install/ui/src/freeipa/ipa.js b/install/ui/src/freeipa/ipa.js
index 0e9fdefb..b3017650 100644
--- a/install/ui/src/freeipa/ipa.js
+++ b/install/ui/src/freeipa/ipa.js
@@ -31,6 +31,16 @@ define(['./jquery',
         './text'],
        function($, JSON, i18n, metadata_provider, builder, reg, text) {
 
+/**
+ * @class
+ * @singleton
+ *
+ * Defined in ipa module. Other modules extend it.
+ *
+ * There is a long-term goal to reduce the number of items in this namespace
+ * and move them to separate modules.
+ *
+ */
 var IPA = function() {
 
     var that = {
@@ -40,6 +50,10 @@ var IPA = function() {
     // live server path
     that.url = '/ipa/ui/';
 
+    /**
+     * jQuery AJAX options used by RPC commands
+     * @property
+     */
     that.ajax_options = {
         type: 'POST',
         contentType: 'application/json',
@@ -48,17 +62,57 @@ var IPA = function() {
         processData: false
     };
 
+    /**
+     * i18n messages
+     * @deprecated
+     * @property {Object}
+     */
     that.messages = {};
+
+    /**
+     * User information
+     *
+     * - output of ipa user-find --whoami
+     */
     that.whoami = {};
 
+    /**
+     * Map of entities
+     * @deprecated
+     * @property {ordered_map}
+     */
     that.entities = $.ordered_map();
+
+    /**
+     * Map of entity factories
+     * @deprecated
+     */
     that.entity_factories = {};
 
+    /**
+     * Number of currently active command calls - controls  visibility of network indicator
+     */
     that.network_call_count = 0;
 
+    /**
+     * UI state
+     * @property {boolean} initialized - Intialization completed:
+     *                                      - metadata
+     *                                      - user information
+     *                                      - server configuration
+     * @property {boolean} logged_kerberos - User authenticated by
+     *                                       Kerberos negotiation
+     * @property {boolean} logged_password - User authenticated by password
+     */
     that.ui = {};
 
-    /* initialize the IPA JSON-RPC helper */
+    /**
+     * Load initialization data and initialize UI
+     * @param {Object} params
+     * @param {string} params.url - URL of JSON RPC interface
+     * @param {Function} params.on_success - success callback
+     * @param {Function} params.on_error - error callback
+     */
     that.init = function(params) {
 
         // if current path matches live server path, use live data
@@ -160,6 +214,12 @@ var IPA = function() {
         batch.execute();
     };
 
+    /**
+     * Prepares `user-find --whoami` command
+     * @protected
+     * @param {boolean} batch - Specifies if it will be used as single command or
+     *                          in a batch.
+     */
     that.get_whoami_command = function(batch) {
         return IPA.command({
             entity: 'user',
@@ -175,6 +235,13 @@ var IPA = function() {
         });
     };
 
+    /**
+     * Executes RPC commands to load metadata
+     * @protected
+     * @param {Object} params
+     * @param {Function} params.on_success
+     * @param {Function} params.on_error
+     */
     that.init_metadata = function(params) {
 
         var objects = IPA.command({
@@ -216,6 +283,12 @@ var IPA = function() {
         metadata_command.execute();
     };
 
+    /**
+     * Register entity factory in global registry
+     * @deprecated
+     * @param {string} name - Entity name
+     * @param {Function} factory - Entity factory
+     */
     that.register = function(name, factory) {
         reg.entity.remove(name);
         reg.entity.register({
@@ -225,15 +298,28 @@ var IPA = function() {
         });
     };
 
+    /**
+     * Return entity instance with given name from global entity registry
+     * @deprecated
+     * @param {string} name - entity name
+     */
     that.get_entity = function(name) {
         return reg.entity.get(name);
     };
 
+    /**
+     * Display network activity indicator
+     */
     that.display_activity_icon = function() {
         that.network_call_count++;
         $('.network-activity-indicator').css('visibility', 'visible');
     };
 
+    /**
+     * Hide network activity indicator
+     *
+     * - based on network_call_count
+     */
     that.hide_activity_icon = function() {
         that.network_call_count--;
 
@@ -249,19 +335,26 @@ var IPA = function() {
 }();
 
 /**
- * Basic object
- *
- * Framework objects created by factories should use this instead of {} when
- * creating base objects. As an alternative they can just set __fw_obj
- * property.
+ * Framework objects created by factories should use this
+ * instead of empty object when creating base objects. As an alternative
+ * they can just set __fw_obj property.
  *
  * __fw_obj property serves for telling the framework that it's instantiated
  * object and not an object specification (spec).
+ *
+ * @class
  */
-IPA.object = function() {
+IPA.object = function(s) {
     return new IPA.obj_cls();
 };
 
+/**
+ * Make request on Kerberos authentication url to initialize Kerberos negotiation.
+ *
+ * Set result to IPA.ui.logged_kerberos.
+ *
+ * @member IPA
+ */
 IPA.get_credentials = function() {
     var status;
 
@@ -289,6 +382,14 @@ IPA.get_credentials = function() {
     return status;
 };
 
+/**
+ * Logout
+ *
+ * - terminate the session.
+ * - redirect to logout landing page on success
+ *
+ * @member IPA
+ */
 IPA.logout = function() {
 
     function show_error(message) {
@@ -335,6 +436,14 @@ IPA.logout = function() {
     $.ajax(request);
 };
 
+/**
+ * Login by username and password
+ *
+ * @member IPA
+ * @param {string} username
+ * @param {string} password
+ * @return {string} Logout status - {password-expired, denied, invalid, success}
+ */
 IPA.login_password = function(username, password) {
 
     var result = 'invalid';
@@ -383,6 +492,17 @@ IPA.login_password = function(username, password) {
     return result;
 };
 
+/**
+ * Reset user's password
+ *
+ * @member IPA
+ * @param {string} username
+ * @param {string} old_password
+ * @param {string} new_password
+ * @return {Object} result
+ * @return {string} result.status
+ * @return {string} result.message
+ */
 IPA.reset_password = function(username, old_password, new_password) {
 
     //possible results: 'ok', 'invalid-password', 'policy-error'
@@ -439,6 +559,13 @@ IPA.reset_password = function(username, old_password, new_password) {
     return result;
 };
 
+/**
+ * Check if password is about to expired (based on
+ * IPA.server_config.ipapwdexpadvnotify). If so, display a notification
+ * message with a link to reset password dialog.
+ *
+ * @member IPA
+ */
 IPA.update_password_expiration = function() {
 
     var now, expires, notify_days, diff, message, container;
@@ -476,6 +603,11 @@ IPA.update_password_expiration = function() {
     }
 };
 
+/**
+ * Show password dialog for self-service change of password.
+ *
+ * @member IPA
+ */
 IPA.password_selfservice = function() {
     var reset_dialog = IPA.user_password_dialog({
         self_service: true,
@@ -495,6 +627,11 @@ IPA.password_selfservice = function() {
     reset_dialog.open();
 };
 
+/**
+ * Parse value as UTC date
+ * @member IPA
+ * @return Data
+ */
 IPA.parse_utc_date = function(value) {
 
     if (!value) return null;
@@ -527,14 +664,17 @@ IPA.parse_utc_date = function(value) {
 /**
  * Call an IPA command over JSON-RPC.
  *
- * Arguments:
- *   name - command name (optional)
- *   entity - command entity (optional)
- *   method - command method
- *   args - list of arguments, e.g. [username]
- *   options - dict of options, e.g. {givenname: 'Pavel'}
- *   on_success - callback function if command succeeds
- *   on_error - callback function if command fails
+ * @class IPA.command
+ *
+ * @param {Object} spec - construct specification
+ * @param {string} spec.name - command name (optional)
+ * @param {string} spec.entity - command entity(name) (optional)
+ * @param {string}  spec.method - command method
+ * @param {string[]}  spec.args - list of arguments, e.g. ['username']
+ * @param {Object} spec.options - dict of options, e.g. {givenname: 'Petr'}
+ * @param {Function} spec.on_success - callback function if command succeeds
+ * @param {Function} spec.on_error - callback function if command fails
+ *
  */
 IPA.command = function(spec) {
 
@@ -542,44 +682,109 @@ IPA.command = function(spec) {
 
     var that = IPA.object();
 
+    /** @property {string} name Name */
     that.name = spec.name;
 
+    /** @property {entity.entity} entity Entity */
     that.entity = spec.entity;
+
+    /** @property {string} method Method */
     that.method = spec.method;
 
+    /** @property {string[]} args Command Arguments */
     that.args = $.merge([], spec.args || []);
+
+    /** @property {Object} options Option map */
     that.options = $.extend({}, spec.options || {});
 
+    /**
+     * Success handler
+     * @property {Function}
+     * @param {Object} data
+     * @param {string} text_status
+     * @param {XMLHttpRequest} xhr
+     */
     that.on_success = spec.on_success;
+
+    /**
+     * Error handler
+     * @property {Function}
+     * @param {XMLHttpRequest} xhr
+     * @param {string} text_status
+     * @param {{name:string,message:string}} error_thrown
+     */
     that.on_error = spec.on_error;
 
+    /**
+     * Allow retrying of execution if previous ended as error
+     *
+     * Manifested by error dialog. Set it to `false` for custom error dialogs or
+     * error handling without any dialog.
+     * @property {Boolean} retry=true
+     */
     that.retry = typeof spec.retry == 'undefined' ? true : spec.retry;
 
+    /** @property {string} error_message Default error message */
     that.error_message = text.get(spec.error_message || '@i18n:dialogs.batch_error_message', 'Some operations failed.');
+
+    /** @property {ordered_map.<number,string>} error_messages Error messages map */
     that.error_messages = $.ordered_map({
         911: 'Missing HTTP referer. <br/> You have to configure your browser to send HTTP referer header.'
     });
 
+    /**
+     * Get command name
+     *
+     * - it's `entity.name + '_' + method`
+     * - or `method`
+     * @return {string}
+     */
     that.get_command = function() {
         return (that.entity ? that.entity+'_' : '') + that.method;
     };
 
+    /**
+     * Add argument
+     * @param {string} arg
+     */
     that.add_arg = function(arg) {
         that.args.push(arg);
     };
 
+    /**
+     * Add arguments
+     * @param {string[]} args
+     */
     that.add_args = function(args) {
         $.merge(that.args, args);
     };
 
+    /**
+     * Set option
+     * @param {string} name
+     * @param {Mixed} value
+     */
     that.set_option = function(name, value) {
         that.options[name] = value;
     };
 
+    /**
+     * Extends options map with another options map
+     *
+     * @param {{opt1:Mixed, opt2:Mixed}} options
+     */
     that.set_options = function(options) {
         $.extend(that.options, options);
     };
 
+    /**
+     * Add value to an option
+     *
+     * - creates a new option if it does not exist yet
+     * - for option overriding use `set_option` method
+     * @param {string} name
+     * @param {Mixed} value
+     */
     that.add_option = function(name, value) {
         var values = that.options[name];
         if (!values) {
@@ -589,14 +794,26 @@ IPA.command = function(spec) {
         values.push(value);
     };
 
+    /**
+     * Get option value
+     * @return {Mixed}
+     */
     that.get_option = function(name) {
         return that.options[name];
     };
 
+    /**
+     * Remove option from option map
+     */
     that.remove_option = function(name) {
         delete that.options[name];
     };
 
+    /**
+     * Execute the command.
+     *
+     * Set `on_success` and/or `on_error` handlers to be informed about result.
+     */
     that.execute = function() {
 
         function dialog_open(xhr, text_status, error_thrown) {
@@ -788,6 +1005,15 @@ IPA.command = function(spec) {
         $.ajax(that.request);
     };
 
+    /**
+     * Parse successful command result and get all errors.
+     * @protected
+     * @param {IPA.command} command
+     * @param {Object} result
+     * @param {string} text_status
+     * @param {XMLHttpRequest} xhr
+     * @return {IPA.error_list}
+     */
     that.get_failed = function(command, result, text_status, xhr) {
         var errors = IPA.error_list();
         if(result && result.failed) {
@@ -809,12 +1035,21 @@ IPA.command = function(spec) {
         return errors;
     };
 
+    /**
+     * Check if command accepts option
+     * @param {string} option_name
+     * @return {Boolean}
+     */
     that.check_option = function(option_name) {
 
         var metadata = IPA.get_command_option(that.get_command(), option_name);
         return metadata !== null;
     };
 
+    /**
+     * Encodes command into JSON-RPC command object
+     * @return {Object}
+     */
     that.to_json = function() {
         var json = {};
 
@@ -827,6 +1062,10 @@ IPA.command = function(spec) {
         return json;
     };
 
+    /**
+     * Encodes command into CLI command string
+     * @return {string}
+     */
     that.to_string = function() {
         var string = that.get_command().replace(/_/g, '-');
 
@@ -844,7 +1083,18 @@ IPA.command = function(spec) {
     return that;
 };
 
-IPA.batch_command = function (spec) {
+/**
+ * Call multiple IPA commands in a batch over JSON-RPC.
+ *
+ * @class IPA.batch_command
+ * @extends IPA.command
+ *
+ * @param {Object} spec
+ * @param {Array.<IPA.command>} spec.commands - IPA commands to be executed
+ * @param {Function} spec.on_success - callback function if command succeeds
+ * @param {Function} spec.on_error - callback function if command fails
+ */
+IPA.batch_command = function(spec) {
 
     spec = spec || {};
 
@@ -852,22 +1102,40 @@ IPA.batch_command = function (spec) {
 
     var that = IPA.command(spec);
 
+    /** @property {IPA.command[]} commands Commands */
     that.commands = [];
+    /** @property {IPA.error_list} errors Errors  */
     that.errors = IPA.error_list();
+
+    /**
+     * Show error if some command fail
+     * @property {Boolean} show_error=true
+     */
     that.show_error = typeof spec.show_error == 'undefined' ?
             true : spec.show_error;
 
+    /**
+     * Add command
+     * @param {IPA.command} command
+     */
     that.add_command = function(command) {
         that.commands.push(command);
         that.add_arg(command.to_json());
     };
 
+    /**
+     * Add commands
+     * @param {IPA.command[]} commands
+     */
     that.add_commands = function(commands) {
         for (var i=0; i<commands.length; i++) {
             that.add_command(commands[i]);
         }
     };
 
+    /**
+     * @inheritDoc
+     */
     that.execute = function() {
         that.errors.clear();
 
@@ -886,6 +1154,16 @@ IPA.batch_command = function (spec) {
         command.execute();
     };
 
+    /**
+     * Internal XHR success handler
+     *
+     * Parses data and looks for errors. `on_success` or `on_error` is then
+     * called.
+     * @protected
+     * @param {Object} data
+     * @param {string} text_status
+     * @param {XMLHttpRequest} xhr
+     */
     that.batch_command_on_success = function(data, text_status, xhr) {
 
         for (var i=0; i<that.commands.length; i++) {
@@ -965,6 +1243,13 @@ IPA.batch_command = function (spec) {
         }
     };
 
+    /**
+     * Internal XHR error handler
+     * @protected
+     * @param {XMLHttpRequest} xhr
+     * @param {string} text_status
+     * @param {{name:string,message:string}} error_thrown
+     */
     that.batch_command_on_error = function(xhr, text_status, error_thrown) {
         // TODO: undefined behavior
         if (that.on_error) {
@@ -975,16 +1260,45 @@ IPA.batch_command = function (spec) {
     return that;
 };
 
-
+/**
+ * Call multiple IPA commands over JSON-RPC separately and wait for every
+ * command's response.
+ *
+ * - concurrent command fails if any command fails
+ * - result is reported when each command finishes
+ *
+ * @class IPA.concurrent_command
+ *
+ * @param {Object} spec - construct specification
+ * @param {Array.<IPA.command>} spec.commands - IPA commands to execute
+ * @param {Function} spec.on_success - callback function if each command succeed
+ * @param {Function} spec.on_error - callback function one command fails
+ *
+ */
 IPA.concurrent_command = function(spec) {
 
     spec = spec || {};
     var that = IPA.object();
 
+    /** @property {IPA.command[]} commands Commands */
     that.commands = [];
+
+    /**
+     * Success handler
+     * @property {Function}
+     */
     that.on_success = spec.on_success;
+
+    /**
+     * Error handler
+     * @property {Function}
+     */
     that.on_error = spec.on_error;
 
+    /**
+     * Add commands
+     * @param {IPA.command[]} commands
+     */
     that.add_commands = function(commands) {
 
         if(commands && commands.length) {
@@ -996,6 +1310,9 @@ IPA.concurrent_command = function(spec) {
         }
     };
 
+    /**
+     * Execute the commands one by one.
+     */
     that.execute = function() {
 
         var command_info, command, i;
@@ -1035,6 +1352,10 @@ IPA.concurrent_command = function(spec) {
         }
     };
 
+    /**
+     * Internal error handler
+     * @protected
+     */
     that.error_handler = function(command_info, xhr, text_status, error_thrown) {
 
         command_info.completed = true;
@@ -1046,6 +1367,10 @@ IPA.concurrent_command = function(spec) {
         that.command_completed();
     };
 
+    /**
+     * Internal success handler
+     * @protected
+     */
     that.success_handler = function(command_info, data, text_status, xhr) {
 
         command_info.completed = true;
@@ -1057,6 +1382,11 @@ IPA.concurrent_command = function(spec) {
         that.command_completed();
     };
 
+    /**
+     * Check if all commands finished.
+     * If so, report it.
+     * @protected
+     */
     that.command_completed = function() {
 
         var all_completed = true;
@@ -1077,6 +1407,10 @@ IPA.concurrent_command = function(spec) {
         }
     };
 
+    /**
+     * Call each command's success handler and `on_success`.
+     * @protected
+     */
     that.on_success_all = function() {
 
         for(var i=0; i < that.commands.length; i++) {
@@ -1095,6 +1429,10 @@ IPA.concurrent_command = function(spec) {
         }
     };
 
+    /**
+     * Call each command's error handler and `on_success`.
+     * @protected
+     */
     that.on_error_all = function() {
 
         if(that.on_error) {
@@ -1116,11 +1454,24 @@ IPA.concurrent_command = function(spec) {
     return that;
 };
 
+/**
+ * Build object with {@link builder}.
+ * @member IPA
+ * @param {Object} spec - contruction spec
+ * @param {Object} context
+ * @param {Object} overrides
+ */
 IPA.build = function(spec, context, overrides) {
 
     return builder.build(null, spec, context, overrides);
 };
 
+/**
+ * Create a object defined by spec with IPA.object as parent.
+ * @member IPA
+ * @param {Object} spec
+ * @return {Object} new object with all properties as spec
+ */
 IPA.default_factory = function(spec) {
 
     spec = spec || {};
@@ -1132,23 +1483,46 @@ IPA.default_factory = function(spec) {
     return that;
 };
 
-/* helper function used to retrieve information about an attribute */
+/**
+ * Helper function used to retrieve information about an object attribute from metadata
+ * @member IPA
+ * @param {string} entity_name
+ * @param {string} name - attribute name
+ */
 IPA.get_entity_param = function(entity_name, name) {
 
     return metadata_provider.get(['@mo-param', entity_name, name].join(':'));
 };
 
+/**
+ * Helper function used to retrieve information about an command argument from metadata
+ * @member IPA
+ * @param {string} command_name
+ * @param {string} arg_name - argument name
+ */
 IPA.get_command_arg = function(command_name, arg_name) {
 
     return metadata_provider.get(['@mc-arg', command_name, arg_name].join(':'));
 };
 
+
+/**
+ * Helper function used to retrieve information about an command option from metadata
+ * @member IPA
+ * @param {string} command_name
+ * @param {string} option_name - argument name
+ */
 IPA.get_command_option = function(command_name, option_name) {
 
     return metadata_provider.get(['@mc-opt', command_name, option_name].join(':'));
 };
 
-/* helper function used to retrieve attr name with members of type `member` */
+/**
+ * Helper function used to retrieve information about an attribute member
+ * @member IPA
+ * @param {string} obj_name - object(entity) name
+ * @param {string} member - attribute member
+ */
 IPA.get_member_attribute = function(obj_name, member) {
 
     var obj = metadata_provider.get('@mo:'+obj_name);
@@ -1169,6 +1543,11 @@ IPA.get_member_attribute = function(obj_name, member) {
     return null;
 };
 
+/**
+ * Create HTML representation of network spinner.
+ * @member IPA
+ * @return {HTMLElement} Network spinner node
+ */
 IPA.create_network_spinner = function(){
     var span = $('<span/>', {
         'class': 'network-activity-indicator'
@@ -1179,6 +1558,18 @@ IPA.create_network_spinner = function(){
     return span;
 };
 
+/**
+ * Dirty dialog
+ *
+ * Should be used as an indication of unsaved changes on page when leaving the
+ * page. Offers user to safe/reset the changes or cancel the action.
+ *
+ * @class
+ * @extends IPA.dialog
+ * @param {Object} spec
+ * @param {IPA.facet} spec.facet - Dirty facet
+ * @param {string} [spec.message] - Displayed message
+ */
 IPA.dirty_dialog = function(spec) {
 
     spec = spec || {};
@@ -1186,9 +1577,14 @@ IPA.dirty_dialog = function(spec) {
     spec.width = spec.width || '25em';
 
     var that = IPA.dialog(spec);
+
+    /** @property {facet.facet} facet Facet*/
     that.facet = spec.facet;
+
+    /** @property {string} message Dirty message*/
     that.message = text.get(spec.message || '@i18n:dialogs.dirty_message');
 
+    /** @inheritDoc */
     that.create = function() {
         that.container.append(that.message);
     };
@@ -1222,12 +1618,25 @@ IPA.dirty_dialog = function(spec) {
         }
     });
 
+    /**
+     * Function which is called when user click on 'update' or 'delete' button
+     */
     that.callback = function() {
     };
 
     return that;
 };
 
+/**
+ * Error dialog
+ *
+ * Serves for notifying an error in RPC command.
+ *
+ * @class
+ * @extends IPA.dialog
+ * @mixins IPA.confirm_mixin
+ * @param {Object} spec
+ */
 IPA.error_dialog = function(spec) {
 
     spec = spec || {};
@@ -1240,20 +1649,32 @@ IPA.error_dialog = function(spec) {
 
     IPA.confirm_mixin().apply(that);
 
+    /** @property {XMLHttpRequest} xhr Command's xhr */
     that.xhr = spec.xhr || {};
+    /** @property {string} text_status Command's text status */
     that.text_status = spec.text_status || '';
+    /** @property {{name:string,message:string}} error_thrown Command's error */
     that.error_thrown = spec.error_thrown || {};
+    /** @property {IPA.command} command Command */
     that.command = spec.command;
+    /** @property {IPA.error_list} errors Errors */
     that.errors = spec.errors;
+    /** @property {string[]} visible_buttons=['retry', 'cancel'] Visible button names */
     that.visible_buttons = spec.visible_buttons || ['retry', 'cancel'];
 
-
+    /**
+     * Beautify error message
+     *
+     * Multi-lined text may contain TAB character as first char of the line
+     * to hint at marking the whole line differently.
+     * @param {jQuery} container Container to add the beautified message.
+     * @param {string} message
+     */
     that.beautify_message = function(container, message) {
         var lines = message.split(/\n/g);
         var line_span;
         for(var i=0; i<lines.length; i++) {
-            // multi-lined text may contain TAB character as first char of the line
-            // to hint at marking the whole line differently
+
             if (lines[i].charAt(0) == '\t') {
                 line_span = $('<p />', {
                     'class': 'error-message-hinted',
@@ -1267,6 +1688,7 @@ IPA.error_dialog = function(spec) {
         }
     };
 
+    /** @inheritDoc */
     that.create = function() {
         if (that.error_thrown.url) {
             $('<p/>', {
@@ -1327,12 +1749,15 @@ IPA.error_dialog = function(spec) {
         }
     };
 
+    /**
+     * Create dialog buttons
+     * @protected
+     */
     that.create_buttons = function() {
-        /**
-        * When a user initially opens the Web UI without a Kerberos
-        * ticket, the messages including the button labels have not
-        * been loaded yet, so the button labels need default values.
-        */
+
+        // When a user initially opens the Web UI without a Kerberos
+        // ticket, the messages including the button labels have not
+        // been loaded yet, so the button labels need default values.
 
         var visible = that.visible_buttons.indexOf('retry') > -1;
         var label = text.get('@i18n:buttons.retry', 'Retry');
@@ -1368,19 +1793,35 @@ IPA.error_dialog = function(spec) {
         });
     };
 
+    /**
+     * Retry handler
+     * @protected
+     */
     that.on_retry = function() {
         that.close();
         that.command.execute();
     };
 
+    /**
+     * OK button handler
+     * @protected
+     */
     that.on_ok = function() {
         that.close();
     };
 
+    /**
+     * Cancel button and negative confirmation handler
+     * @protected
+     */
     that.on_cancel = function() {
         that.close();
     };
 
+    /**
+     * Positive confirmation handler
+     * @protected
+     */
     that.on_confirm = function() {
         if (that.visible_buttons.indexOf('retry') > -1) that.on_retry();
         else that.on_ok();
@@ -1391,13 +1832,23 @@ IPA.error_dialog = function(spec) {
     return that;
 };
 
+/**
+ * Error list
+ *
+ * Collection for RPC command errors.
+ *
+ * @class IPA.error_list
+ * @private
+ */
 IPA.error_list = function() {
     var that = IPA.object();
 
+    /** Clear errors */
     that.clear = function() {
         that.errors = [];
     };
 
+    /** Add error */
     that.add = function(command, name, message, status) {
         that.errors.push({
             command: command,
@@ -1407,10 +1858,15 @@ IPA.error_list = function() {
         });
     };
 
+    /** Add errors */
     that.add_range = function(error_list) {
         that.errors = that.errors.concat(error_list.errors);
     };
 
+    /**
+     * Check if there are no errors
+     * @return {Boolean}
+     */
     that.is_empty = function () {
         return that.errors.length === 0;
     };
@@ -1419,6 +1875,14 @@ IPA.error_list = function() {
     return that;
 };
 
+/**
+ * Error handler for IPA.command which handles error #4304 as success.
+ *
+ * 4304 is raised when part of an operation succeeds and the part that failed
+ * isn't critical.
+ * @member IPA
+ * @param {IPA.entity_adder_dialog} adder_dialog
+ */
 IPA.create_4304_error_handler = function(adder_dialog) {
 
     var set_pkey = function(result) {
@@ -1460,6 +1924,16 @@ IPA.create_4304_error_handler = function(adder_dialog) {
     };
 };
 
+/**
+ * Unauthorized dialog
+ *
+ * Notifies that user's session is expired. It supports forms-based authentication
+ * and password reset when password is expired.
+ *
+ * @class IPA.unauthorized_dialog
+ * @extends IPA.error_dialog
+ * @param {Object} spec
+ */
 IPA.unauthorized_dialog = function(spec) {
 
     spec = spec || {};
@@ -1515,14 +1989,18 @@ IPA.unauthorized_dialog = function(spec) {
 
     var that = IPA.error_dialog(spec);
 
+    /** @inheritDoc */
     that.title = spec.title || text.get('@i18n:login.login', "Login");
 
+    /** @property {string} message Session expired message   */
     that.message = text.get(spec.message || '@i18n:ajax.401.message',
                     "Your session has expired. Please re-login.");
 
+    /** @property {string} form_auth_msg Forms authentication message */
     that.form_auth_msg = text.get(spec.form_auth_msg || '@i18n:login.form_auth',
                     "To login with username and password, enter them in the fields below then click Login.");
 
+    /** @property {string} krb_auth_msg Kerberos authentication message */
     that.krb_auth_msg = text.get(spec.krb_auth_msg || '@i18n:login.krb_auth_msg',
                     " To login with Kerberos, please make sure you" +
                     " have valid tickets (obtainable via kinit) and " +
@@ -1531,21 +2009,29 @@ IPA.unauthorized_dialog = function(spec) {
 
     that.krb_auth_msg = that.krb_auth_msg.replace('${host}', window.location.hostname);
 
+    /** @property {string} form_auth_failed Forms authentication failure message */
     that.form_auth_failed = "<p><strong>Please re-enter your username or password</strong></p>" +
                 "<p>The password or username you entered is incorrect. " +
                 "Please try again (make sure your caps lock is off).</p>" +
                 "<p>If the problem persists, contact your administrator.</p>";
 
+    /** @property {string} password_expired Password expired message */
     that.password_expired = "Your password has expired. Please enter a new password.";
 
+    /** @property {string} denied Login denied message */
     that.denied = "Sorry you are not allowed to access this service.";
 
+    /** @inheritDoc */
     that.create = function() {
 
         that.session_expired_form();
         that.create_reset_form();
     };
 
+    /**
+     * Create session expired form
+     * @protected
+     */
     that.session_expired_form = function() {
         that.session_form = $('<div\>').appendTo(that.container);
 
@@ -1585,6 +2071,10 @@ IPA.unauthorized_dialog = function(spec) {
         that.username_widget.value_changed.attach(that.on_username_change);
     };
 
+    /**
+     * Create password reset form
+     * @protected
+     */
     that.create_reset_form = function() {
 
         that.reset_form = $('<div\>', {
@@ -1611,6 +2101,10 @@ IPA.unauthorized_dialog = function(spec) {
         that.verify_password_widget = that.widgets.get_widget('reset.verify_password');
     };
 
+    /**
+     * Create dialog buttons
+     * @protected
+     */
     that.create_buttons = function() {
 
         that.buttons.empty();
@@ -1649,12 +2143,17 @@ IPA.unauthorized_dialog = function(spec) {
         });
     };
 
+    /** @inheritDoc */
     that.open = function() {
         that.dialog_open();
         that.show_session_form();
         that.check_error_reason();
     };
 
+    /**
+     * Check if response contains IPA specific rejection reason.
+     * @protected
+     */
     that.check_error_reason = function() {
         if (this.xhr) {
             var reason = this.xhr.getResponseHeader("X-IPA-Rejection-Reason");
@@ -1664,6 +2163,10 @@ IPA.unauthorized_dialog = function(spec) {
         }
     };
 
+    /**
+     * User name field value change handler
+     * @protected
+     */
     that.on_username_change = function() {
 
         var password_field = that.fields.get_field('password');
@@ -1672,6 +2175,11 @@ IPA.unauthorized_dialog = function(spec) {
         if (!user_specified) that.password_widget.clear();
     };
 
+    /**
+     * Enable fields with given name
+     * @protected
+     * @param {string[]} field_names
+     */
     that.enable_fields = function(field_names) {
 
         var field, fields, i, enable;
@@ -1683,6 +2191,10 @@ IPA.unauthorized_dialog = function(spec) {
         }
     };
 
+    /**
+     * Shows session expired form. Hides other.
+     * @protected
+     */
     that.show_session_form = function() {
 
         that.current_view = 'session';
@@ -1693,6 +2205,10 @@ IPA.unauthorized_dialog = function(spec) {
         that.username_widget.focus_input();
     };
 
+    /**
+     * Shows password reset form. Hides other.
+     * @protected
+     */
     that.show_reset_form = function() {
 
         that.current_view = 'reset';
@@ -1706,6 +2222,11 @@ IPA.unauthorized_dialog = function(spec) {
         that.new_password_widget.focus_input();
     };
 
+    /**
+     * Show login error message - based on reason
+     * @protected
+     * @param {"invalid"|"denied"|string} reason
+     */
     that.show_login_error_message = function(reason) {
         var errors = {
             'invalid': that.form_auth_failed,
@@ -1720,6 +2241,10 @@ IPA.unauthorized_dialog = function(spec) {
         }
     };
 
+    /**
+     * Cancel handler
+     * @protected
+     */
     that.on_cancel = function() {
 
         that.username_widget.clear();
@@ -1731,6 +2256,10 @@ IPA.unauthorized_dialog = function(spec) {
         that.show_session_form();
     };
 
+    /**
+     * Initiates login procedure
+     * @protected
+     */
     that.on_login = function() {
 
         var username = that.username_widget.save();
@@ -1760,6 +2289,10 @@ IPA.unauthorized_dialog = function(spec) {
         }
     };
 
+    /**
+     * Login success handler
+     * @protected
+     */
     that.on_login_success = function() {
         that.login_error_box.css('display', 'none');
 
@@ -1769,6 +2302,10 @@ IPA.unauthorized_dialog = function(spec) {
         that.on_retry();
     };
 
+    /**
+     * Initiates password reset procedure
+     * @protected
+     */
     that.on_reset = function() {
         if (!that.validate()) return;
 
@@ -1791,6 +2328,10 @@ IPA.unauthorized_dialog = function(spec) {
         }
     };
 
+    /**
+     * Password reset success handler
+     * @protected
+     */
     that.on_reset_success = function() {
 
         that.login_error_box.css('display', 'none');
@@ -1807,7 +2348,10 @@ IPA.unauthorized_dialog = function(spec) {
         that.on_login();
     };
 
-    //replaces confirm_mixin method
+    /**
+     * Key up handler for proper keyboard usage.
+     * @protected
+     */
     that.on_key_up = function(event) {
 
         if (that.switching) {
@@ -1836,6 +2380,15 @@ IPA.unauthorized_dialog = function(spec) {
     return that;
 };
 
+/**
+ * Shorten text to desired number of characters.
+ *
+ * If shortened, '...' is appended to the shortened text.
+ * @member IPA
+ * @param {string} value - text to shorten
+ * @param {number} max_length - maximum number of characters
+ * @return {string} shortened text
+ */
 IPA.limit_text = function(value, max_length) {
 
     if (!value) return '';
@@ -1849,6 +2402,13 @@ IPA.limit_text = function(value, max_length) {
     return limited_text;
 };
 
+
+/**
+ * Convert strings to options.
+ * @member IPA
+ * @param {string[]} values - options as strings
+ * @return {Array.<{value,label}>} options
+ */
 IPA.create_options = function(values) {
 
     var options = [];
@@ -1870,6 +2430,19 @@ IPA.create_options = function(values) {
     return options;
 };
 
+/**
+ * Check if value is not defined.
+ *
+ * True when:
+ *
+ * - value is undefined or null or ''
+ * - value is empty Array
+ * - value is Array with an empty string ('')
+ * - value is empty Object- {}
+ * @member IPA
+ * @param value - value to check
+ * @return {boolean}
+ */
 IPA.is_empty = function(value) {
 
     var empty = false;
@@ -1893,11 +2466,29 @@ IPA.is_empty = function(value) {
     return empty;
 };
 
+/**
+ * Check if value is not null or undefined.
+ * @member IPA
+ * @param value
+ * @param {boolean} check_empty_str - additional check for empty string
+ */
 IPA.defined = function(value, check_empty_str) {
     return value !== null && value !== undefined &&
         ((check_empty_str && value !== '') || !check_empty_str);
 };
 
+
+/**
+ * Check if arrays differ.
+ *
+ * False when:
+ *
+ * - length and items or arrays equals (===)
+ * - undefined state of both is the same
+ * @member IPA
+ * @param a
+ * @param b
+ */
 IPA.array_diff = function(a, b) {
 
     if (a === b || (!a && !b)) return false;
@@ -1913,10 +2504,23 @@ IPA.array_diff = function(a, b) {
     return false;
 };
 
+/**
+ * Shows confirm dialog with message
+ * @member IPA
+ * @param {string} msg - message
+ * @return {boolean} confirmed state
+ */
 IPA.confirm = function(msg) {
     return window.confirm(msg);
 };
 
+/**
+ * Display positive notification message
+ * @member IPA
+ * @param {string} message
+ * @param {number} [timeout=IPA.config.message_timeout] - duration for the
+ *                 message to be displayed [ms]
+ */
 IPA.notify_success = function(message, timeout) {
 
     if (!message) return; // don't show undefined, null and such
@@ -1951,6 +2555,12 @@ IPA.notify_success = function(message, timeout) {
     }, timeout || IPA.config.message_timeout);
 };
 
+/**
+ * Get number of succeeded commands in RPC command
+ * @member IPA
+ * @param {Object} data - RPC command data
+ * @return {number}
+ */
 IPA.get_succeeded = function(data) {
     var succeeded = data.result.completed;
 
@@ -1966,6 +2576,15 @@ IPA.get_succeeded = function(data) {
     return succeeded;
 };
 
+/**
+ * Global configuration
+ * @member IPA
+ * @property {number} default_priority - command default priority. Used in
+ *                                        'update info' concept
+ * @property {number} message_timeout - timeout for notification messages
+ * @property {number} message_fadeout_time
+ * @property {number} message_fadein_time
+ */
 IPA.config = {
     default_priority: 500,
     message_timeout: 3000, // [ms]