diff --git a/platform/core/src/capabilities/PersistenceCapability.js b/platform/core/src/capabilities/PersistenceCapability.js
index 96d5f4f378..d26426d82a 100644
--- a/platform/core/src/capabilities/PersistenceCapability.js
+++ b/platform/core/src/capabilities/PersistenceCapability.js
@@ -1,20 +1,35 @@
 /*global define*/
 
-/**
- * Defines the "persistence" capability, used to indicate
- * that changes to an object should be written to some
- * underlying store.
- *
- * Current implementation is a stub that simply triggers
- * a refresh on modified views, which is a necessary
- * side effect of persisting the object.
- */
+
 define(
     function () {
         'use strict';
 
+        /**
+         * Defines the `persistence` capability, used to trigger the
+         * writing of changes to a domain object to an underlying
+         * persistence store.
+         *
+         * @param {PersistenceService} persistenceService the underlying
+         *        provider of persistence capabilities.
+         * @param {string} SPACE the name of the persistence space to
+         *        use (this is an arbitrary string, useful in principle
+         *        for distinguishing different persistence stores from
+         *        one another.)
+         * @param {DomainObject} the domain object which shall expose
+         *        this capability
+         *
+         * @constructor
+         */
         function PersistenceCapability(persistenceService, SPACE, domainObject) {
-            var self = {
+            return {
+                /**
+                 * Persist any changes which have been made to this
+                 * domain object's model.
+                 * @returns {Promise} a promise which will be resolved
+                 *          if persistence is successful, and rejected
+                 *          if not.
+                 */
                 persist: function () {
                     return persistenceService.updateObject(
                         SPACE,
@@ -22,15 +37,20 @@ define(
                         domainObject.getModel()
                     );
                 },
+                /**
+                 * Get the space in which this domain object is persisted;
+                 * this is useful when, for example, decided which space a
+                 * newly-created domain object should be persisted to (by
+                 * default, this should be the space of its containing
+                 * object.)
+                 *
+                 * @returns {string} the name of the space which should
+                 *          be used to persist this object
+                 */
                 getSpace: function () {
                     return SPACE;
-                },
-                invoke: function () {
-                    return self;
                 }
             };
-
-            return self;
         }
 
         return PersistenceCapability;