[Status] Add JSDoc

platform/status/src/StatusCapability.js

@@ -26,15 +26,42 @@ define(
     function () {
         'use strict';
 
+        /**
+         * The `status` capability can be used to attach information
+         * about the state of a domain object, expressed as simple
+         * string flags.
+         *
+         * Representations of domain objects will also receive CSS
+         * classes which reflect their current status.
+         * (@see platform/status.StatusRepresenter)
+         *
+         * @param {platform/status.StatusService} statusService
+         *        the service which will track domain object status
+         *        within the application.
+         * @param {DomainObject} the domain object whose status will
+         *        be tracked.
+         * @constructor
+         * @memberof platform/status
+         */
         function StatusCapability(statusService, domainObject) {
             this.statusService = statusService;
             this.domainObject = domainObject;
         }
 
+        /**
+         * Get all status flags currently set for this domain object.
+         * @returns {string[]} all current status flags.
+         */
         StatusCapability.prototype.get = function () {
             return this.statusService.getStatus(this.domainObject.getId());
         };
 
+        /**
+         * Set a status flag on this domain object.
+         * @param {string} status the status to set
+         * @param {boolean} state true if the domain object should
+         *        possess this status, false if it should not
+         */
         StatusCapability.prototype.set = function (status, state) {
             return this.statusService.setStatus(
                 this.domainObject.getId(),
@@ -43,6 +70,14 @@ define(
             );
         };
 
+        /**
+         * Listen for changes in this domain object's status.
+         * @param {Function} callback function to invoke on changes;
+         *        called with the new status of the domain object, as an
+         *        array of strings
+         * @returns {Function} a function which can be used to stop
+         *          listening to status changes for this domain object.
+         */
         StatusCapability.prototype.listen = function (callback) {
             return this.statusService.listen(
                 this.domainObject.getId(),

platform/status/src/StatusRepresenter.js

@@ -26,8 +26,23 @@ define(
     function () {
         'use strict';
 
-        var STATUS_CLASS_PREFIX = "l-status-";
+        var STATUS_CLASS_PREFIX = "s-status-";
 
+        /**
+         * Adds/removes CSS classes to `mct-representation`s to reflect the
+         * current status of represented domain objects, as reported by
+         * their `status` capability.
+         *
+         * Statuses are prefixed with `s-status-` to build CSS class names.
+         * As such, when a domain object has the status "pending", its
+         * representations will have the CSS class `s-status-pending`.
+         *
+         * @param {angular.Scope} scope the representation's scope object
+         * @param element the representation's jqLite-wrapped DOM element
+         * @implements {Representer}
+         * @constructor
+         * @memberof platform/status
+         */
         function StatusRepresenter(scope, element) {
             this.element = element;
             this.lastClasses = [];

platform/status/src/StatusService.js

@@ -28,12 +28,26 @@ define(
 
         var STATUS_PREFIX = "status:";
 
+        /**
+         * The `statusService` maintains information about the current
+         * status of specific domain objects within the system. Status
+         * is represented as string flags which are present when a
+         * domain object possesses that status, and false when it does
+         * not.
+         *
+         * @param {platform/core.Topic} topic the `topic` service, used
+         *        to create/use named listeners.
+         * @constructor
+         * @memberof platform/status
+         */
         function StatusService(topic) {
             this.statusTable = {};
             this.topic = topic;
         }
 
         /**
+         * Get all status flags currently set for a domain object.
+         * @param {string} id the identifier of the domain object
          * @returns {string[]} an array containing all status flags currently
          *          applicable to the object with this identifier
          */
@@ -41,6 +55,13 @@ define(
             return this.statusTable[id] || [];
         };
 
+        /**
+         * Set a status flag for a domain object.
+         * @param {string} id the identifier of the domain object
+         * @param {string} status the status to set
+         * @param {boolean} state true if the domain object should
+         *        possess this status, false if it should not
+         */
         StatusService.prototype.setStatus = function (id, status, state) {
             this.statusTable[id] = this.statusTable[id] || [];
             this.statusTable[id] = this.statusTable[id].filter(function (s) {
@@ -52,6 +73,15 @@ define(
             this.topic(STATUS_PREFIX + id).notify(this.statusTable[id]);
         };
 
+        /**
+         * Listen for changes in a domain object's status.
+         * @param {string} id the identifier of the domain object
+         * @param {Function} callback function to invoke on changes;
+         *        called with the new status of the domain object, as an
+         *        array of strings
+         * @returns {Function} a function which can be used to stop
+         *          listening to status changes for this domain object.
+         */
         StatusService.prototype.listen = function (id, callback) {
             return this.topic(STATUS_PREFIX + id).listen(callback);
         };