[Common UI] Add JSDoc

Add JSDoc to classes from commonUI bundles. WTD-574.

platform/commonUI/browse/src/BrowseController.js

@@ -11,37 +11,63 @@ define(
         var ROOT_OBJECT = "ROOT";
 
         /**
+         * The BrowseController is used to populate the initial scope in Browse
+         * mode. It loads the root object from the objectService and makes it
+         * available in the scope for Angular template's; this is the point at
+         * which Angular templates first have access to the domain object
+         * hierarchy.
          *
          * @constructor
          */
         function BrowseController($scope, objectService, navigationService) {
+            // Callback for updating the in-scope reference to the object
+            // that is currently navigated-to.
             function setNavigation(domainObject) {
                 $scope.navigatedObject = domainObject;
-                //$scope.$apply("navigatedObject");
             }
 
+            // Load the root object, put it in the scope.
+            // Also, load its immediate children, and (possibly)
+            // navigate to one of them, so that navigation state has
+            // a useful initial value.
             objectService.getObjects([ROOT_OBJECT]).then(function (objects) {
                 var composition = objects[ROOT_OBJECT].useCapability("composition");
                 $scope.domainObject = objects[ROOT_OBJECT];
                 if (composition) {
                     composition.then(function (c) {
-                        // Navigate to the last root level component (usually "mine")
+                        // Check if an object has been navigated-to already...
                         if (!navigationService.getNavigation()) {
+                            // If not, pick a default as the last
+                            // root-level component (usually "mine")
                             navigationService.setNavigation(c[c.length - 1]);
                         } else {
+                            // Otherwise, just expose it in the scope
                             $scope.navigatedObject = navigationService.getNavigation();
                         }
                     });
                 }
             });
 
+            // Listen for changes in navigation state.
+            navigationService.addListener(setNavigation);
+
+            // Clean up when the scope is destroyed
             $scope.$on("$destroy", function () {
                 navigationService.removeListener(setNavigation);
             });
 
-            navigationService.addListener(setNavigation);
-
             return {
+                /**
+                 * Navigate to a specific domain object.
+                 *
+                 * This is exposed so that the browse tree has a callback
+                 * to invoke when the user clicks on a new object to navigate
+                 * to it.
+                 *
+                 * @method
+                 * @memberof BrowseController
+                 * @param {DomainObject} domainObject the object to navigate to
+                 */
                 setNavigation: function (domainObject) {
                     navigationService.setNavigation(domainObject);
                 }

platform/commonUI/browse/src/creation/CreateAction.js

@@ -9,11 +9,27 @@ define(
         "use strict";
 
         /**
+         * The Create Action is performed to create new instances of
+         * domain objects of a specific type. This is the action that
+         * is performed when a user uses the Create menu.
          *
          * @constructor
+         * @param {Type} type the type of domain object to create
+         * @param {DomainObject} parent the domain object that should
+         *        act as a container for the newly-created object
+         *        (note that the user will have an opportunity to
+         *        override this)
+         * @param {ActionContext} context the context in which the
+         *        action is being performed
+         * @param {DialogService} dialogService the dialog service
+         *        to use when requesting user input
+         * @param {CreationService} creationService the creation service,
+         *        which handles the actual instantiation and persistence
+         *        of the newly-created domain object
          */
         function CreateAction(type, parent, context, dialogService, creationService) {
             /*
+             Overview of steps in object creation:
 
              1. Show dialog
                a. Prepare dialog contents
@@ -26,12 +42,15 @@ define(
                b. Add new id to composition
              4. Persist destination container
                a. ...use persistence capability.
-
              */
 
             function perform() {
+                // The wizard will handle creating the form model based
+                // on the type...
                 var wizard = new CreateWizard(type, parent);
 
+                // Create and persist the new object, based on user
+                // input.
                 function persistResult(formValue) {
                     var parent = wizard.getLocation(formValue),
                         newModel = wizard.createModel(formValue);
@@ -49,7 +68,24 @@ define(
             }
 
             return {
+                /**
+                 * Create a new object of the given type.
+                 * This will prompt for user input first.
+                 * @method
+                 * @memberof CreateAction
+                 */
                 perform: perform,
+
+                /**
+                 * Get metadata about this action. This includes fields:
+                 * * `name`: Human-readable name
+                 * * `key`: Machine-readable identifier ("create")
+                 * * `glyph`: Glyph to use as an icon for this action
+                 * * `description`: Human-readable description
+                 * * `context`: The context in which this action will be performed.
+                 *
+                 * @return {object} metadata about the create action
+                 */
                 getMetadata: function () {
                     return {
                         key: 'create',

platform/commonUI/browse/src/creation/CreateActionProvider.js

@@ -9,20 +9,42 @@ define(
         "use strict";
 
         /**
+         * The CreateActionProvider is an ActionProvider which introduces
+         * a Create action for each creatable domain object type.
          *
          * @constructor
+         * @param {TypeService} typeService the type service, used to discover
+         *        available types
+         * @param {DialogService} dialogService the dialog service, used by
+         *        specific Create actions to get user input to populate the
+         *        model of the newly-created domain object.
+         * @param {CreationService} creationService the creation service (also
+         *        introduced in this bundle), responsible for handling actual
+         *        object creation.
          */
         function CreateActionProvider(typeService, dialogService, creationService) {
             return {
+                /**
+                 * Get all Create actions which are applicable in the provided
+                 * context.
+                 * @memberof CreateActionProvider
+                 * @method
+                 * @returns {CreateAction[]}
+                 */
                 getActions: function (actionContext) {
                     var context = actionContext || {},
                         key = context.key,
                         destination = context.domainObject;
 
+                    // We only provide Create actions, and we need a
+                    // domain object to serve as the container for the
+                    // newly-created object (although the user may later
+                    // make a different selection)
                     if (key !== 'create' || !destination) {
                         return [];
                     }
 
+                    // Introduce one create action per type
                     return typeService.listTypes().map(function (type) {
                         return new CreateAction(
                             type,