diff --git a/core/modules/workspace/src/Plugin/Derivative/Workspace.php b/core/modules/workspace/src/Plugin/Derivative/Workspace.php
index 2d8c46b735..e4dcb60f65 100644
--- a/core/modules/workspace/src/Plugin/Derivative/Workspace.php
+++ b/core/modules/workspace/src/Plugin/Derivative/Workspace.php
@@ -9,7 +9,7 @@
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
- * Class Workspace
+ * Derive an upstream plugin for each workspace.
  */
 class Workspace extends DeriverBase implements ContainerDeriverInterface {
 
@@ -36,6 +36,12 @@ public static function create(ContainerInterface $container, $base_plugin_id) {
     );
   }
 
+  /**
+   * Add a workspace plugin per workspace, with an ID in the format
+   * 'workspace:{id}', for example 'workspace:live'.
+   *
+   * {@inheritdoc}
+   */
   public function getDerivativeDefinitions($base_plugin_definition) {
     $workspaces = $this->workspaceStorage->loadMultiple();
     foreach ($workspaces as $workspace) {
diff --git a/core/modules/workspace/src/Plugin/Upstream/Workspace.php b/core/modules/workspace/src/Plugin/Upstream/Workspace.php
index 4bec2595cc..5fe2b8ecc2 100644
--- a/core/modules/workspace/src/Plugin/Upstream/Workspace.php
+++ b/core/modules/workspace/src/Plugin/Upstream/Workspace.php
@@ -9,7 +9,8 @@
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
- * Provides a 'Workspace' upstream plugin.
+ * Provides a 'Workspace' upstream plugin to allow a workspace to be set as a
+ * source and / or target for content replication.
  *
  * @Upstream(
  *   id = "workspace",
diff --git a/core/modules/workspace/src/Replication/DefaultReplicator.php b/core/modules/workspace/src/Replication/DefaultReplicator.php
index b1ca88af80..ed44738b51 100644
--- a/core/modules/workspace/src/Replication/DefaultReplicator.php
+++ b/core/modules/workspace/src/Replication/DefaultReplicator.php
@@ -11,26 +11,35 @@
 use Drupal\workspace\WorkspaceManagerInterface;
 
 /**
- * Class DefaultReplicator
+ * The default replicator service, replicating from one workspace to another on
+ * a single site.
  */
 class DefaultReplicator implements ReplicationInterface {
 
   /**
+   * The workspace manager.
+   *
    * @var \Drupal\workspace\WorkspaceManagerInterface
    */
   protected $workspaceManager;
 
   /**
+   * The changes factory.
+   *
    * @var \Drupal\workspace\Changes\ChangesFactoryInterface
    */
   protected $changesFactory;
 
   /**
+   * The entity type manager.
+   *
    * @var \Drupal\Core\Entity\EntityTypeManagerInterface
    */
   protected $entityTypeManager;
 
   /**
+   * The sequence index.
+   *
    * @var \Drupal\workspace\Index\SequenceIndexInterface
    */
   protected $sequenceIndex;
@@ -51,10 +60,11 @@ public function __construct(WorkspaceManagerInterface $workspace_manager, Change
   }
 
   /**
-   * @param \Drupal\workspace\UpstreamInterface $source
-   * @param \Drupal\workspace\UpstreamInterface $target
-   *q
-   * @return bool
+   * Only use this replicator if the source and target are workspaces. The
+   * Upstream plugin ID would be something like 'workspace:live' for the live
+   * workspace.
+   *
+   * {@inheritdoc}
    */
   public function applies(UpstreamInterface $source, UpstreamInterface $target) {
     list($source_plugin, $source_id) = explode(':', $source->getPluginId());
@@ -67,6 +77,10 @@ public function applies(UpstreamInterface $source, UpstreamInterface $target) {
   }
 
   /**
+   * Replicating content from one workspace to another on the same site roughly
+   * following the same protocol as CouchDB replication
+   * (http://docs.couchdb.org/en/2.1.0/replication/protocol.html).
+   *
    * {@inheritdoc}
    */
   public function replicate(UpstreamInterface $source, UpstreamInterface $target) {
diff --git a/core/modules/workspace/src/Replication/ReplicationManager.php b/core/modules/workspace/src/Replication/ReplicationManager.php
index 88af5e360c..20014e6e2b 100644
--- a/core/modules/workspace/src/Replication/ReplicationManager.php
+++ b/core/modules/workspace/src/Replication/ReplicationManager.php
@@ -5,7 +5,7 @@
 use Drupal\workspace\UpstreamInterface;
 
 /**
- * Class ReplicationManager
+ * Manage the replication tagged services.
  */
 class ReplicationManager {
 
@@ -22,6 +22,9 @@ public function addReplicator(ReplicationInterface $replicator, $priority) {
   }
 
   /**
+   * Find all replicators that apply for the source and target upstream plugins
+   * and run the replication for each replicator.
+   *
    * @param \Drupal\workspace\UpstreamInterface $source
    * @param \Drupal\workspace\UpstreamInterface $target
    *
diff --git a/core/modules/workspace/src/UpstreamInterface.php b/core/modules/workspace/src/UpstreamInterface.php
index 7ad6f31086..4b51d51666 100644
--- a/core/modules/workspace/src/UpstreamInterface.php
+++ b/core/modules/workspace/src/UpstreamInterface.php
@@ -5,15 +5,25 @@
 use Drupal\Component\Plugin\PluginInspectionInterface;
 
 /**
- * Interface UpstreamInterface
+ * An upstream is a source or a target for replication. For example it could be
+ * a workspace, a remote site, a non-drupal application or a database such as
+ * CouchDB.
+ *
+ * When a replication happens the replicator will determine if it should run
+ * based on the source and target upstream plugins. Then the replication will
+ * use data from the upstream plugins to perform the replication. For example an
+ * internal replication might just need the workspace IDs, but a contrib module
+ * performing an external replication may need host name, port, username,
+ * password etc.
  */
 interface UpstreamInterface extends PluginInspectionInterface {
 
   /**
-   * Return the label of the upstream.
+   * Returns the label of the upstream. This is used as a form label where a user
+   * selects the target for replicating to.
    *
    * @return string
-   *   The of the upstream.
+   *   The label of the upstream.
    */
   public function getLabel();