diff --git a/core/modules/layout/lib/Drupal/layout/LayoutBundle.php b/core/modules/layout/lib/Drupal/layout/LayoutBundle.php
index 92b4796..59b8513 100644
--- a/core/modules/layout/lib/Drupal/layout/LayoutBundle.php
+++ b/core/modules/layout/lib/Drupal/layout/LayoutBundle.php
@@ -14,8 +14,9 @@
  * Layout dependency injection container.
  */
 class LayoutBundle extends Bundle {
+
   /**
-   * Overrides Symfony\Component\HttpKernel\Bundle\Bundle.
+   * Overrides Symfony\Component\HttpKernel\Bundle\Bundle::build().
    */
   public function build(ContainerBuilder $container) {
     // Register the LayoutManager class with the dependency injection container.
diff --git a/core/modules/layout/lib/Drupal/layout/Plugin/Derivative/Layout.php b/core/modules/layout/lib/Drupal/layout/Plugin/Derivative/Layout.php
index ea186a9..0f7485a 100644
--- a/core/modules/layout/lib/Drupal/layout/Plugin/Derivative/Layout.php
+++ b/core/modules/layout/lib/Drupal/layout/Plugin/Derivative/Layout.php
@@ -11,7 +11,21 @@
 use Drupal\Component\Plugin\Derivative\DerivativeInterface;
 use Drupal\Core\Config\FileStorage;
 
+/**
+ * Layout plugin derivative definition.
+ */
 class Layout implements DerivativeInterface {
+
+  /**
+   * List of derivatives.
+   *
+   * @type array
+   *   Associative array keyed by 'provider__layoutname' where provider is the
+   *   module or theme name and layoutname is the .yml filename, such as
+   *   'bartik__page' or 'layout__onecol'. The values of the array are associative
+   *   arrays themselves with metadata about the layout such as 'template', 'css',
+   *   'admin css' and so on.
+   */
   protected $derivatives = array();
 
   /**
@@ -30,6 +44,8 @@ public function getDerivativeDefinition($derivative_id, array $base_plugin_defin
    */
   public function getDerivativeDefinitions(array $base_plugin_definition) {
     $available_layout_providers = array();
+
+    // Add all modules as possible layout providers.
     foreach (module_list() as $module) {
       $available_layout_providers[$module] = array(
         'type' => 'module',
@@ -37,6 +53,8 @@ public function getDerivativeDefinitions(array $base_plugin_definition) {
         'dir' => drupal_get_path('module', $module),
       );
     }
+
+    // Add all themes as possible layout providers.
     foreach (list_themes() as $theme_id => $theme) {
       $available_layout_providers[$theme_id] = array(
         'type' => 'theme',
@@ -44,9 +62,12 @@ public function getDerivativeDefinitions(array $base_plugin_definition) {
         'dir' => drupal_get_path('theme', $theme->name),
       );
     }
+
     foreach ($available_layout_providers as $provider) {
+      // Looks for layouts in the 'layout' directory under the module/theme.
+      // There could be subdirectories under there with one layout defined
+      // in each.
       $dir = $provider['dir'] . DIRECTORY_SEPARATOR . 'layout';
-      // If the directory structure exists, look for layouts.
       if (file_exists($dir)) {
         $this->iterateDirectories($dir, $provider);
       }
@@ -61,9 +82,13 @@ protected function iterateDirectories($dir, $provider) {
     $directories = new DirectoryIterator($dir);
     foreach ($directories as $fileinfo) {
       if ($fileinfo->isDir() && !$fileinfo->isDot()) {
+        // Keep discovering in subdirectories to arbitrary depth.
         $this->iterateDirectories($fileinfo->getPathname(), $provider);
       }
       elseif ($fileinfo->isFile() && $fileinfo->getExtension() == 'yml') {
+        // Declarative layout definitions are defined with a .yml file in a
+        // layout subdirectory. This provides all information about the layout
+        // such as layout markup template and CSS and JavaScript files to use.
         $directory = new FileStorage($fileinfo->getPath());
         $this->derivatives[$provider['provider'] . '__' .  $fileinfo->getBasename('.yml')] = $directory->read($fileinfo->getBasename('.yml'));
         $this->derivatives[$provider['provider'] . '__' .  $fileinfo->getBasename('.yml')]['path'] = $fileinfo->getPath();
diff --git a/core/modules/layout/lib/Drupal/layout/Plugin/LayoutMapper.php b/core/modules/layout/lib/Drupal/layout/Plugin/LayoutMapper.php
index daeaee8..c8f1d71 100644
--- a/core/modules/layout/lib/Drupal/layout/Plugin/LayoutMapper.php
+++ b/core/modules/layout/lib/Drupal/layout/Plugin/LayoutMapper.php
@@ -46,7 +46,7 @@ public function getInstance(array $options) {
       foreach ($blocks as $config) {
         $conf['regions'][$config['region']][$config['config_id']] = array();
       }
-      return $this->manager->createInstance('default_layout:bartik__bartik', $conf);
+      return $this->manager->createInstance('default_layout:bartik__page', $conf);
     }
   }
 
@@ -57,4 +57,4 @@ function sort($a, $b) {
       return $weight;
     }
   }
-}
\ No newline at end of file
+}
diff --git a/core/modules/layout/lib/Drupal/layout/Plugin/Type/LayoutManager.php b/core/modules/layout/lib/Drupal/layout/Plugin/Type/LayoutManager.php
index 181edfc..e9852f3 100644
--- a/core/modules/layout/lib/Drupal/layout/Plugin/Type/LayoutManager.php
+++ b/core/modules/layout/lib/Drupal/layout/Plugin/Type/LayoutManager.php
@@ -13,12 +13,19 @@
 use Drupal\Component\Plugin\Factory\ReflectionFactory;
 use Drupal\layout\Plugin\LayoutMapper;
 
+/**
+ * Layout plugin manager.
+ */
 class LayoutManager extends PluginManagerBase {
   protected $defaults = array(
     'class' => 'Drupal\layout\Plugin\layout\layout\DefaultLayout'
   );
 
+  /**
+   * Overrides Drupal\Component\Plugin\PluginManagerBase::__construct().
+   */
   public function __construct() {
+    // Create layout plugin derivatives from declaratively defined layouts.
     $this->discovery = new DerivativeDiscoveryDecorator(new AnnotatedClassDiscovery('layout', 'layout'));
     $this->factory = new ReflectionFactory($this);
     $this->mapper = new LayoutMapper($this);
diff --git a/core/modules/layout/lib/Drupal/layout/Plugin/layout/layout/DefaultLayout.php b/core/modules/layout/lib/Drupal/layout/Plugin/layout/layout/DefaultLayout.php
index 154ed45..4906fa5 100644
--- a/core/modules/layout/lib/Drupal/layout/Plugin/layout/layout/DefaultLayout.php
+++ b/core/modules/layout/lib/Drupal/layout/Plugin/layout/layout/DefaultLayout.php
@@ -19,7 +19,12 @@
  * )
  */
 class DefaultLayout extends PluginBase implements LayoutInterface {
+
+  /**
+   * Overrides Drupal\Component\Plugin\PluginBase::__construct().
+   */
   public function __construct(array $configuration, $plugin_id, DiscoveryInterface $discovery) {
+    // Get definition by discovering the declarative information.
     $definition = $discovery->getDefinition($plugin_id);
     foreach ($definition['regions'] as $region => $title) {
       if (!isset($configuration['regions'][$region])) {
@@ -30,7 +35,7 @@ public function __construct(array $configuration, $plugin_id, DiscoveryInterface
   }
 
   /**
-   * Overrides Drupal\layout\Plugin\LayoutInterface::getRegions().
+   * Implements Drupal\layout\Plugin\LayoutInterface::getRegions().
    */
   public function getRegions() {
     $definition = $this->getDefinition();
@@ -56,6 +61,7 @@ public function addCss() {
    */
   public function addAdminCss() {
     $definition = $this->getDefinition();
+    // Fall back on regular CSS for the admin page if admin CSS not provided.
     $files = isset($definition['admin css']) ? $definition['admin css'] : $definition['css'];
     if (is_string($files)) {
       $files = array($files);
@@ -91,6 +97,7 @@ public function addAdminJs() {
       $files = $definition['admin js'];
     }
     elseif (isset($definition['js'])) {
+      // Fall back on regular JS for the admin page if admin JS not provided.
       $files = $definition['js'];
     }
     if (is_string($files)) {
@@ -102,19 +109,15 @@ public function addAdminJs() {
   }
 
   /**
-   * Overrides Drupal\layout\Plugin\LayoutInterface::renderLayout().
-   *
-   * @todo
-   *   The $regions parameter is here only temporarily. It allows the caller
-   *   to pass already rendered regions, while layout/block configuration code
-   *   is still in progress.
+   * Implements Drupal\layout\Plugin\LayoutInterface::renderLayout().
    */
   public function renderLayout($admin = FALSE) {
     $definition = $this->getDefinition();
 
-    // Render all regions not already rendered by the caller.
+    // Render all regions needed for this layout.
+    $regions = array();
     foreach ($this->getRegions() as $region => $title) {
-      if (!isset($regions[$region]) && isset($this->configuration['regions'][$region])) {
+      if (isset($this->configuration['regions'][$region])) {
         foreach ($this->configuration['regions'][$region] as $block_id => $configuration) {
           $block = block_load($block_id, $configuration);
           if ($block->access()) {