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.

4 files changed, 156 insertions, 49 deletions

diff --git a/install/ui/src/freeipa/navigation/Menu.js b/install/ui/src/freeipa/navigation/Menu.js
index 677171d4d..a5e96d3c9 100644
--- a/install/ui/src/freeipa/navigation/Menu.js
+++ b/install/ui/src/freeipa/navigation/Menu.js
@@ -18,7 +18,6 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-
 define(['dojo/_base/declare',
        'dojo/store/Memory',
        'dojo/_base/array',
@@ -29,67 +28,45 @@ define(['dojo/_base/declare',
        '../text'
        ], function(declare, Memory_store, array, lang, Observable, Evented, reg, text) {
 
-/**
- * Menu store
- *
- * Maintains menu hierarchy and selection state.
- */
-return declare([Evented], {
 
+return declare([Evented],
     /**
-     * Following properties can be specified in menu item spec:
-     * @property {String} name
-     * @property {String} label
-     * @property {String} title
-     * @property {Number} position: position among siblings
-     * @property {menu_item_spec_array} children
-     * @property {String} entity: entity name
-     * @property {String} facet: facet name
-     * @property {Boolean} hidden: menu item is no visible, but can serve for
-     *                             other evaluations (nested entities)
-     *
-     * Following properties are not in created menu item:
-     *   - children
+     * Menu store
      *
+     * Maintains menu hierarchy and selection state.
      *
-     * Following properties can be stored in menu item at runtime:
-     *
-     * @property {Boolean} selected
-     * @property {String} parent: name of parent menu item
-     * @property {String} selected_child: last selected child. Can be set even
-     *                                    if the child is not selected
+     * @class navigation.Menu
      *
      */
-
+    {
     /**
      * Menu name
-     * @type String
+     * @property {String}
      */
     name: null,
 
     /**
      * Dojo Store of menu items
-     * @type: Store
+     * @property {Store}
      */
     items: null,
 
     /**
     * Delimiter used in name creation
     * To avoid having multiple menu items with the same name.
-    * @type String
+    * @property {String}
     */
     path_delimiter: '/',
 
     /**
      * Selected menu items
-     * @type Array of menu items
+     * @property {Array}
      */
     selected: [],
 
     /**
      * Default search options: sort by position
-     *
-     * @type Object
+     * @property {Object}
      */
     search_options: { sort: [{attribute:'position'}]},
 
@@ -97,8 +74,8 @@ return declare([Evented], {
      * Takes a spec of menu item.
      * Normalizes item's name, parent, adds children if specified
      *
-     * @param {menu_item} items
-     * @param {String|menu_item} parent
+     * @param {Object} item - spec
+     * @param {string/Object} parent - name or menu item
      * @param {Object} options
      */
     add_item: function(item, parent, options) {
@@ -168,6 +145,10 @@ return declare([Evented], {
         return true;
     },
 
+    /**
+     * Add multiple items
+     * @param {Array} items - spec of items
+     */
     add_items: function(/* Array */ items) {
         array.forEach(items, function(item) {
             this.add_item(item);
@@ -177,8 +158,8 @@ return declare([Evented], {
     /**
      * Query internal data store by using default search options.
      *
-     * @param Object Query filter
-     * @return QueryResult
+     * @param {Object} Query filter
+     * @return {QueryResult}
      */
     query: function(query) {
         return this.items.query(query, this.search_options);
@@ -186,6 +167,7 @@ return declare([Evented], {
 
     /**
      * Marks item and all its parents as selected.
+     * @private
      */
     _select: function(item) {
 
@@ -202,7 +184,7 @@ return declare([Evented], {
 
     /**
      * Selects a menu item and all it's ancestors.
-     * @param {string|menu_item} Menu item to select
+     * @param {string/navigation.MenuItem} item menu item to select
      */
     select: function(item) {
 
@@ -234,6 +216,11 @@ return declare([Evented], {
         return select_state;
     },
 
+    /**
+     * @param {Object} spec - Specification object
+     * @param {Array} spec.items - Menu items
+     * @param {string} spec.name - Name
+     */
     constructor: function(spec) {
         spec = spec || {};
         this.items = new Observable( new Memory_store({
@@ -246,4 +233,4 @@ return declare([Evented], {
         declare.safeMixin(this, spec);
     }
 }); //declare freeipa.menu
-}); //define
\ No newline at end of file
+}); //define
diff --git a/install/ui/src/freeipa/navigation/MenuItem.js b/install/ui/src/freeipa/navigation/MenuItem.js
new file mode 100644
index 000000000..1b2358cf6
--- /dev/null
+++ b/install/ui/src/freeipa/navigation/MenuItem.js
@@ -0,0 +1,98 @@
+/*  Authors:
+ *    Petr Vobornik <pvoborni@redhat.com>
+ *
+ * Copyright (C) 2013 Red Hat
+ * see file 'COPYING' for use and warranty information
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * This is a virtual object which serves only for documentation purposes. It
+ * describes what properties has the created menu item and what can be part
+ * of menu item object specification.
+ *
+ * Following properties are not in created in menu item:
+ *
+ * - children
+ *
+ * Following properties may be part of menu item at runtime:
+ *
+ * - selected
+ * - parent
+ * - selected_child
+ *
+ * @class navigation.MenuItem
+ * @abstract
+ */
+var MenuItem = {
+    /**
+     * Name - menu item identifier
+     */
+    name: '',
+
+    /**
+     * Visible text
+     */
+    label: '',
+
+    /**
+     * Title/Tooltip
+     */
+    title: '',
+
+    /**
+     * Position for ordering
+     */
+    position: 0,
+
+    /**
+     * Children
+     *
+     * - next navigation level
+     * @property {Array.<navigation.MenuItem>}
+     */
+    children: null,
+
+    /**
+     * Entity name
+     */
+    entity: '',
+
+    /**
+     * Facet name
+     */
+    facet: '',
+
+    /**
+     * Control item visibility but can serve for other evaluations (nested entities)
+     */
+    hidden: '',
+
+    /**
+     * Runtime property
+     * Should not be set by hand. Indicates whether item is selected.
+     */
+    selected: false,
+
+    /**
+     * Parent menu item's name
+     */
+    parent: null,
+
+    /**
+     * Some child is selectd. Runtime property.
+     */
+    selected_child: null
+};
diff --git a/install/ui/src/freeipa/navigation/Router.js b/install/ui/src/freeipa/navigation/Router.js
index 3ac8357ed..a3b2a6791 100644
--- a/install/ui/src/freeipa/navigation/Router.js
+++ b/install/ui/src/freeipa/navigation/Router.js
@@ -30,31 +30,34 @@ define(['dojo/_base/declare',
        function(declare, lang, array, Evented, ioquery, router, IPA, reg) {
 
     /**
-    * Class navigation
+     * Router
+     *
     * This component keeps menu and routes in sync. It signalizes
     * other components to display facet by sending 'show-facet' event.
     * Other components can use navigate_to_* methods to change currently
     * displayed facet. This change can be canceled in 'facet-change'
     * event handler.
+    * @class navigation.Router
     */
     var navigation = declare([Evented], {
 
         /**
          * Holds references to register route handlers.
          * Can be used for unregistering routes.
-         * @type Array
+         * @property {Array.<Function>}
          */
         route_handlers: [],
 
         /**
          *  Prefix of all routes for this navigation. Useful for multiple
          *  navigation objects in one application.
-         *  @type String
+         *  @property {string}
          */
         route_prefix: '',
 
         /**
          * Variations of entity routes
+         * @property {Array.<string>}
          */
         entity_routes: [
             '/e/:entity/:facet/:pkeys/*args',
@@ -66,6 +69,7 @@ define(['dojo/_base/declare',
 
         /**
          * Variations of simple page routes
+         * @property {Array.<string>}
          */
         page_routes: [
             '/p/:page/*args',
@@ -75,7 +79,7 @@ define(['dojo/_base/declare',
         /**
          * Used during facet changing. Set it to true in 'facet-change'
          * event handler to stop the change.
-         * @type Boolean
+         * @property {boolean}
          */
         canceled: false,
 
@@ -83,7 +87,7 @@ define(['dojo/_base/declare',
          * Flag to indicate that next hash change should not invoke showing a
          * facet.
          * Main purpose: updating hash.
-         * @type Boolen
+         * @property {boolean}
          */
         ignore_next: false,
 
@@ -92,8 +96,8 @@ define(['dojo/_base/declare',
          * Register a route-handler pair to a dojo.router
          * Handler will be run in context of this object
          *
-         * @param {string|array} route or routes to register
-         * @param {function} handler to be associated with the route(s)
+         * @param {string|Array.<string>} route or routes to register
+         * @param {Function} handler to be associated with the route(s)
          */
         register_route: function(route, handler) {
             // TODO: add multiple routes for one handler
@@ -121,6 +125,7 @@ define(['dojo/_base/declare',
         /**
          * Handler for entity routes
          * Shouldn't be invoked directly.
+         * @param {Object} event route event args
          */
         entity_route_handler: function(event) {
 
@@ -157,6 +162,7 @@ define(['dojo/_base/declare',
         /**
          * General facet route handler
          * Shouldn't be invoked directly.
+         * @param {Object} event route event args
          */
         page_route_handler: function(event) {
 
@@ -249,8 +255,8 @@ define(['dojo/_base/declare',
         /**
          * Changes hash to supplied
          *
-         * @param {String} Hash to set
-         * @param {Boolean} Whether to suppress following hash change handler
+         * @param {string} Hash to set
+         * @param {boolean} Whether to suppress following hash change handler
          */
         update_hash: function(hash, ignore_change) {
             this.ignore_next = !!ignore_change;
@@ -299,7 +305,7 @@ define(['dojo/_base/declare',
         /**
          * Creates hash from supplied facet and state.
          *
-         * @param {facet} facet
+         * @param {facet.facet} facet
          * @param {Object} state
          */
         create_hash: function(facet, state) {
@@ -346,6 +352,11 @@ define(['dojo/_base/declare',
             return keys;
         },
 
+        /**
+         * Raise 'error'
+         * @protected
+         * @fires error
+         */
         _error: function(msg, type, context) {
 
             this.emit('error', {
diff --git a/install/ui/src/freeipa/navigation/menu_spec.js b/install/ui/src/freeipa/navigation/menu_spec.js
index 66116b583..9d4c5eff9 100644
--- a/install/ui/src/freeipa/navigation/menu_spec.js
+++ b/install/ui/src/freeipa/navigation/menu_spec.js
@@ -20,7 +20,15 @@
 
 define([], function() {
 
+/**
+ * Specification of menu
+ * @singleton
+ * @class navigation.menu_spec
+ */
 var nav = {};
+    /**
+     * Admin menu
+     */
     nav.admin = {
     name: 'admin',
     items: [
@@ -131,6 +139,9 @@ var nav = {};
     ]
 };
 
+/**
+ * Self-service menu
+ */
 nav.self_service = {
     name: 'self-service',
     items: [