[Common UI] Add JSDoc

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

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,