[Common UI] Add JSDoc for CreateMenuController

Add JSDoc and clarifying comments to the CreateMenuController,
which is responsible for maintaining an up-to-date set of
Create actions for a given domain object. WTD-574.

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

@@ -9,18 +9,26 @@ define(
         "use strict";
 
         /**
+         * Controller for the Create menu; maintains an up-to-date
+         * set of Create actions based on the currently-selected
+         * domain object.
          *
          * @constructor
          */
         function CreateMenuController($scope) {
+            // Update the set of Create actions
             function refreshActions() {
-                var actionCapability = $scope.action;
+                $scope.createActions = $scope.action ?
-                if (actionCapability) {
+                        $scope.action.getActions('create') :
-                    $scope.createActions =
+                        [];
-                        actionCapability.getActions('create');
-                }
             }
 
+            // Listen for new instances of the represented object's
+            // "action" capability. This is provided by the mct-representation
+            // for the Create button.
+            // A watch is needed here (instead of invoking action.getActions
+            // directly) because different action instances may be returned
+            // with each call.
             $scope.$watch("action", refreshActions);
         }