core/includes/common.inc                           |    7 ++---
 .../Drupal/Core/Asset/Aggregate/AssetAggregate.php |    1 +
 core/lib/Drupal/Core/Asset/AssetGraph.php          |   15 ++++++++---
 core/lib/Drupal/Core/Asset/AssetInterface.php      |    9 +++----
 .../Drupal/Core/Asset/AssetLibraryRepository.php   |   12 +++++----
 core/lib/Drupal/Core/Asset/BaseAsset.php           |   21 ++++++++++++---
 .../Core/Asset/Collection/AssetCollection.php      |    4 ++-
 .../Collection/AssetCollectionBasicInterface.php   |    2 ++
 .../Asset/Collection/AssetCollectionInterface.php  |   28 +++++++++++---------
 .../Drupal/Core/Asset/Collection/AssetLibrary.php  |   10 +++++++
 .../Iterator/AssetSubtypeFilterIterator.php        |    2 +-
 .../Iterator/RecursiveBasicCollectionIterator.php  |    3 ++-
 core/lib/Drupal/Core/Asset/DependencyInterface.php |   13 ++++-----
 .../Asset/Exception/AssetTypeMismatchException.php |    2 +-
 .../Core/Asset/Exception/FrozenObjectException.php |    2 +-
 .../UnsupportedAsseticBehaviorException.php        |    2 +-
 core/lib/Drupal/Core/Asset/ExternalAsset.php       |   11 ++++++--
 .../Drupal/Core/Asset/Factory/AssetCollector.php   |    7 ++---
 .../Core/Asset/Factory/AssetCollectorInterface.php |   17 +++++++-----
 core/lib/Drupal/Core/Asset/FileAsset.php           |   11 ++++----
 .../Core/Asset/GroupSort/AssetGraphSorter.php      |   13 ++++++---
 .../Asset/GroupSort/AssetGroupSorterInterface.php  |   12 +++++----
 .../Drupal/Core/Asset/GroupSort/CssGraphSorter.php |   11 ++++++--
 .../Asset/GroupSort/OptimallyGroupedTSLVisitor.php |    6 +++--
 .../Core/Asset/Metadata/AssetMetadataBag.php       |    4 ++-
 .../Core/Asset/Metadata/AssetMetadataInterface.php |    3 ++-
 .../Asset/Metadata/DefaultAssetMetadataFactory.php |    3 ++-
 .../Asset/Metadata/MetadataFactoryInterface.php    |    8 +++---
 .../Core/Asset/RelativePositionInterface.php       |   14 +++++-----
 core/lib/Drupal/Core/Asset/StringAsset.php         |   16 ++++++++---
 30 files changed, 180 insertions(+), 89 deletions(-)

diff --git a/core/includes/common.inc b/core/includes/common.inc
index 52b8cb7..7f103b4 100644
--- a/core/includes/common.inc
+++ b/core/includes/common.inc
@@ -1670,8 +1670,7 @@ function drupal_collect_assets($data, $options, $type = '') {
 
   $collection = ($collection instanceof \Drupal\Core\Asset\Collection\AssetCollection) ? $collection : new \Drupal\Core\Asset\Collection\AssetCollection();
   if (!$collector instanceof \Drupal\Core\Asset\Factory\AssetCollector) {
-    $collector = new \Drupal\Core\Asset\Factory\AssetCollector();
-    $collector->setCollection($collection);
+    $collector = new \Drupal\Core\Asset\Factory\AssetCollector($collection);
   }
 
   if ($data instanceof \Drupal\Core\Asset\AssetInterface) {
@@ -1689,6 +1688,8 @@ function drupal_collect_assets($data, $options, $type = '') {
     return;
   }
 
+  // TODO: simplify
+  // $type is 'css' or 'js', $options['type'] is 'file', 'external' or 'inline'.
   $collector->create($type, $options['type'], $data, $options);
 }
 
@@ -2589,7 +2590,7 @@ function drupal_pre_render_scripts($elements) {
  * @see drupal_render()
  */
 function drupal_process_attached($elements, $dependency_check = FALSE, $collect = TRUE) {
-  // TODO duplicates the start of drupal_collect_attached()...just for now.
+  // TODO duplicates the start of drupal_collect_assets()...just for now.
   $collection = &drupal_static('global_asset_collection', FALSE);
   $collector = &drupal_static('global_asset_collector', FALSE);
 
diff --git a/core/lib/Drupal/Core/Asset/Aggregate/AssetAggregate.php b/core/lib/Drupal/Core/Asset/Aggregate/AssetAggregate.php
index 53599db..b0fa33d 100644
--- a/core/lib/Drupal/Core/Asset/Aggregate/AssetAggregate.php
+++ b/core/lib/Drupal/Core/Asset/Aggregate/AssetAggregate.php
@@ -290,4 +290,5 @@ public function clearFilters() {
   public final function getValues() {
     throw new UnsupportedAsseticBehaviorException("Drupal does not use or support Assetic's 'values' concept.");
   }
+
 }
diff --git a/core/lib/Drupal/Core/Asset/AssetGraph.php b/core/lib/Drupal/Core/Asset/AssetGraph.php
index 3c60f9f..679e8e8 100644
--- a/core/lib/Drupal/Core/Asset/AssetGraph.php
+++ b/core/lib/Drupal/Core/Asset/AssetGraph.php
@@ -6,6 +6,7 @@
  */
 
 namespace Drupal\Core\Asset;
+
 use Gliph\Exception\InvalidVertexTypeException;
 use Gliph\Graph\DirectedAdjacencyList;
 
@@ -26,7 +27,7 @@
  *
  * For ordering, however, the full set must be inspected to determine whether or
  * not the other asset is already present. If it is, a directed edge can be
- * declared; if it is not.
+ * declared; if it is not, then ….
  *
  * This class eases the process of determining what to do with ordering
  * declarations by implementing a more sophisticated addVertex() mechanism,
@@ -34,6 +35,7 @@
  * declarations that have not yet been realized.
  *
  * TODO add stuff that tracks data about unresolved successors/predecessors
+ * TODO finish the ordering paragraph
  */
 class AssetGraph extends DirectedAdjacencyList {
 
@@ -45,13 +47,13 @@ class AssetGraph extends DirectedAdjacencyList {
   /**
    * Creates a new AssetGraph object.
    *
-   * AssetGraphs are a specialization of DirectedAdjacencyGraph that is tailored
+   * AssetGraphs are a specialization of DirectedAdjacencyList that is tailored
    * to handling the ordering information carried by RelativePositionInterface
    * instances.
    *
    * @param bool $process
    *   Whether or not to automatically process positioning metadata as vertices
-   *   are added. This should be left as TRUE in most every user-facing case;
+   *   are added. This should be left as TRUE in almost every user-facing case;
    *   the primary use case for setting FALSE is the creation of a graph
    *   transpose.
    */
@@ -107,6 +109,9 @@ protected function processNewVertex(AssetInterface $vertex) {
         // Normalize to id string.
         $predecessor = is_string($predecessor) ? $predecessor : $predecessor->id();
 
+        // Add a directed edge indicating that this asset vertex succeeds
+        // another asset vertex. Or, if that other asset does not yet have a
+        // vertex in the AssetGraph, set up a watch for it.
         if (isset($this->verticesById[$predecessor])) {
           $this->addDirectedEdge($vertex, $this->verticesById[$predecessor]);
         }
@@ -122,6 +127,9 @@ protected function processNewVertex(AssetInterface $vertex) {
         // Normalize to id string.
         $successor = is_string($successor) ? $successor : $successor->id();
 
+        // Add a directed edge indicating that this asset vertex preceeds
+        // another asset vertex. Or, if that other asset does not yet have a
+        // vertex in the AssetGraph, set up a watch for it.
         if (isset($this->verticesById[$successor])) {
           $this->addDirectedEdge($this->verticesById[$successor], $vertex);
         }
@@ -164,4 +172,5 @@ public function transpose() {
 
     return $graph;
   }
+
 }
diff --git a/core/lib/Drupal/Core/Asset/AssetInterface.php b/core/lib/Drupal/Core/Asset/AssetInterface.php
index ac1512b..e35eba1 100644
--- a/core/lib/Drupal/Core/Asset/AssetInterface.php
+++ b/core/lib/Drupal/Core/Asset/AssetInterface.php
@@ -11,7 +11,7 @@
 use Drupal\Core\Asset\Metadata\AssetMetadataInterface;
 
 /**
- * Represents a CSS or Javascript asset.
+ * Represents a CSS or JavaScript asset.
  *
  * This interface extends the AssetInterface provided by Assetic to facilitate
  * different behaviors by individual assets.
@@ -21,7 +21,7 @@
   /**
    * Returns the metadata bag for this asset.
    *
-   * @return AssetMetadataInterface
+   * @return \Drupal\Core\Asset\Metadata\AssetMetadataInterface
    */
   public function getMetadata();
 
@@ -29,9 +29,7 @@ public function getMetadata();
    * Indicates whether or not this asset is eligible for preprocessing.
    *
    * Assets that are marked as not preprocessable will always be passed directly
-   * to the browser without aggregation or minification. Assets that are marked
-   * as eligible for preprocessing will be included in any broader aggregation
-   * logic that has been configured.
+   * to the browser without aggregation or minification.
    *
    * @return bool
    */
@@ -56,4 +54,5 @@ public function id();
    * @return string
    */
   public function getAssetType();
+
 }
diff --git a/core/lib/Drupal/Core/Asset/AssetLibraryRepository.php b/core/lib/Drupal/Core/Asset/AssetLibraryRepository.php
index 487d9e6..fbb5cc7 100644
--- a/core/lib/Drupal/Core/Asset/AssetLibraryRepository.php
+++ b/core/lib/Drupal/Core/Asset/AssetLibraryRepository.php
@@ -16,9 +16,9 @@
 class AssetLibraryRepository {
 
   /**
-   * An array of loaded AssetLibrary objects.
+   * An array of loaded \Drupal\Core\Asset\Collection\AssetLibrary objects.
    *
-   * @var AssetLibrary[]
+   * @var \Drupal\Core\Asset\Collection\AssetLibrary[]
    */
   protected $libraries;
 
@@ -88,13 +88,13 @@ public function has($key) {
   /**
    * Resolves declared dependencies into an array of library objects.
    *
-   * @param DependencyInterface $asset
+   * @param \Drupal\Core\Asset\DependencyInterface $asset
    *   The asset whose dependencies should be resolved.
    *
    * @param bool $attach
    *   Whether to automatically attach resolved dependencies to the given asset.
    *
-   * @return AssetLibrary[]
+   * @return \Drupal\Core\Asset\Collection\AssetLibrary[]
    *   An array of AssetLibraryInterface objects if any dependencies were found;
    *   otherwise, an empty array.
    */
@@ -125,7 +125,8 @@ public function resolveDependencies(DependencyInterface $asset, $attach = TRUE)
   /**
    * Returns an array of library names.
    *
-   * @return array An array of library names
+   * @return array
+   *   An array of library names.
    */
   public function getNames() {
     return array_keys($this->libraries);
@@ -137,4 +138,5 @@ public function getNames() {
   public function clear() {
     $this->libraries = array();
   }
+
 }
diff --git a/core/lib/Drupal/Core/Asset/BaseAsset.php b/core/lib/Drupal/Core/Asset/BaseAsset.php
index 650417b..6bcf64b 100644
--- a/core/lib/Drupal/Core/Asset/BaseAsset.php
+++ b/core/lib/Drupal/Core/Asset/BaseAsset.php
@@ -15,7 +15,7 @@
  *
  * This is an amalgam of Assetic\Asset\BaseAsset (copied directly) with
  * implementations of the additional methods specified by Drupal's own
- * Drupal\Core\Asset\AssetInterface.
+ * \Drupal\Core\Asset\AssetInterface.
  *
  * The methods load() and getLastModified() are left undefined, although a
  * reusable doLoad() method is available to child classes.
@@ -27,12 +27,27 @@
    */
   protected $metadata;
 
+  /**
+   * The asset library's dependencies (on other asset libraries).
+   *
+   * @var array
+   */
   protected $dependencies = array();
 
-  protected $successors = array();
-
+  /**
+   * The asset library's predecing assets (not asset libraries!).
+   *
+   * @var array
+   */
   protected $predecessors = array();
 
+  /**
+   * The asset library's succeeding assets (not asset libraries!).
+   *
+   * @var array
+   */
+  protected $successors = array();
+
   public function __construct(AssetMetadataInterface $metadata, $filters = array(), $sourceRoot = NULL, $sourcePath = NULL) {
     $this->metadata = $metadata;
     parent::__construct($filters, $sourceRoot, $sourcePath);
diff --git a/core/lib/Drupal/Core/Asset/Collection/AssetCollection.php b/core/lib/Drupal/Core/Asset/Collection/AssetCollection.php
index 52a9f69..bedeb99 100644
--- a/core/lib/Drupal/Core/Asset/Collection/AssetCollection.php
+++ b/core/lib/Drupal/Core/Asset/Collection/AssetCollection.php
@@ -6,6 +6,7 @@
  */
 
 namespace Drupal\Core\Asset\Collection;
+
 use Assetic\Asset\AssetInterface as AsseticAssetInterface;
 use Drupal\Core\Asset\Collection\AssetCollectionInterface;
 use Drupal\Core\Asset\AssetInterface;
@@ -227,7 +228,7 @@ public function resolveLibraries(AssetLibraryRepository $repository) {
   }
 
   /**
-   * Checks if the asset library is frozen, throws an exception if it is.
+   * Checks if the asset collection is frozen, throws an exception if it is.
    *
    * @param string $method
    *   The name of the method that was originally called.
@@ -239,4 +240,5 @@ protected function attemptWrite($method) {
       throw new FrozenObjectException(sprintf('AssetCollectionInterface::%s was called; writes cannot be performed on a frozen collection.', $method));
     }
   }
+
 }
diff --git a/core/lib/Drupal/Core/Asset/Collection/AssetCollectionBasicInterface.php b/core/lib/Drupal/Core/Asset/Collection/AssetCollectionBasicInterface.php
index b1394cb..3db227c 100644
--- a/core/lib/Drupal/Core/Asset/Collection/AssetCollectionBasicInterface.php
+++ b/core/lib/Drupal/Core/Asset/Collection/AssetCollectionBasicInterface.php
@@ -6,6 +6,7 @@
  */
 
 namespace Drupal\Core\Asset\Collection;
+
 use Drupal\Core\Asset\AssetInterface;
 use Assetic\Asset\AssetInterface as AsseticAssetInterface;
 use Drupal\Core\Asset\Exception\AssetTypeMismatchException;
@@ -166,5 +167,6 @@ public function each();
    * @return \Traversable
    */
   public function eachLeaf();
+
 }
 
diff --git a/core/lib/Drupal/Core/Asset/Collection/AssetCollectionInterface.php b/core/lib/Drupal/Core/Asset/Collection/AssetCollectionInterface.php
index 81d6f31..9bd3027 100644
--- a/core/lib/Drupal/Core/Asset/Collection/AssetCollectionInterface.php
+++ b/core/lib/Drupal/Core/Asset/Collection/AssetCollectionInterface.php
@@ -6,6 +6,7 @@
  */
 
 namespace Drupal\Core\Asset\Collection;
+
 use Drupal\Core\Asset\AssetInterface;
 use Drupal\Core\Asset\AssetLibraryRepository;
 
@@ -21,15 +22,15 @@
    *
    * If an asset is present in both collections, as identified by
    * AssetInterface::id(), the asset from the passed collection will
-   * supercede the asset in this collection.
+   * supersede the asset in this collection.
    *
-   * @param AssetCollectionInterface $collection
+   * @param \Drupal\Core\Asset\Collection\AssetCollectionInterface $collection
    *   The collection to merge.
    *
    * @param bool $freeze
    *   Whether to freeze the provided collection after merging. Defaults to TRUE.
    *
-   * @return AssetCollectionInterface
+   * @return \Drupal\Core\Asset\Collection\AssetCollectionInterface
    *   The current asset collection.
    */
   public function mergeCollection(AssetCollectionInterface $collection, $freeze = TRUE);
@@ -42,7 +43,7 @@ public function mergeCollection(AssetCollectionInterface $collection, $freeze =
    *
    * TODO put this on the basic interface so aggregates have it, too?
    *
-   * @return AssetCollectionInterface
+   * @return \Drupal\Core\Asset\Collection\AssetCollectionInterface
    *   The current asset collection.
    */
   public function freeze();
@@ -62,7 +63,7 @@ public function isFrozen();
   public function getCss();
 
   /**
-   * Returns all contained JS assets in a traversable form.
+   * Returns all contained JavaScript assets in a traversable form.
    *
    * @return \Traversable
    */
@@ -73,7 +74,7 @@ public function getJs();
    *
    * @param $callback
    *
-   * @return AssetCollectionInterface
+   * @return \Drupal\Core\Asset\Collection\AssetCollectionInterface
    *   The current asset collection.
    */
   public function uksort($callback);
@@ -81,7 +82,7 @@ public function uksort($callback);
   /**
    * Sorts contained assets via ksort() on their ids.
    *
-   * @return AssetCollectionInterface
+   * @return \Drupal\Core\Asset\Collection\AssetCollectionInterface
    *   The current asset collection.
    */
   public function ksort();
@@ -89,7 +90,7 @@ public function ksort();
   /**
    * Reverses the sort order of the contained assets.
    *
-   * @return AssetCollectionInterface
+   * @return \Drupal\Core\Asset\Collection\AssetCollectionInterface
    *   The current asset collection.
    */
   public function reverse();
@@ -105,10 +106,10 @@ public function reverse();
    *   slash-delimited, with the first part being the module owner and the
    *   second part being the library name.
    *
-   * @return AssetCollectionInterface
+   * @return \Drupal\Core\Asset\Collection\AssetCollectionInterface
    *   The current asset collection.
    *
-   * @see AssetCollectionInterface::resolveLibraries()
+   * @see \Drupal\Core\Asset\Collection\AssetCollectionInterface::resolveLibraries()
    */
   public function addUnresolvedLibrary($key);
 
@@ -131,7 +132,7 @@ public function getUnresolvedLibraries();
   /**
    * Empties the collection of its unresolved library keys.
    *
-   * @return AssetCollectionInterface
+   * @return \Drupal\Core\Asset\Collection\AssetCollectionInterface
    *   The current asset collection.
    */
   public function clearUnresolvedLibraries();
@@ -143,12 +144,13 @@ public function clearUnresolvedLibraries();
    * directly to this collection, as well as those libraries included indirectly
    * via a contained asset's declared dependencies.
    *
-   * @param AssetLibraryRepository $repository
+   * @param \Drupal\Core\Asset\AssetLibraryRepository $repository
    *   The AssetLibraryRepository to use for resolving library keys into
    *   AssetLibrary objects.
    *
-   * @return AssetCollectionInterface
+   * @return \Drupal\Core\Asset\Collection\AssetCollectionInterface
    *   The current asset collection.
    */
   public function resolveLibraries(AssetLibraryRepository $repository);
+
 }
diff --git a/core/lib/Drupal/Core/Asset/Collection/AssetLibrary.php b/core/lib/Drupal/Core/Asset/Collection/AssetLibrary.php
index 4e807bd..6b67baf 100644
--- a/core/lib/Drupal/Core/Asset/Collection/AssetLibrary.php
+++ b/core/lib/Drupal/Core/Asset/Collection/AssetLibrary.php
@@ -49,8 +49,18 @@ class AssetLibrary extends AssetCollection implements DependencyInterface, Relat
    */
   protected $dependencies = array();
 
+  /**
+   * The asset library's predecing assets (not asset libraries!).
+   *
+   * @var array
+   */
   protected $predecessors = array();
 
+  /**
+   * The asset library's succeeding assets (not asset libraries!).
+   *
+   * @var array
+   */
   protected $successors = array();
 
   /**
diff --git a/core/lib/Drupal/Core/Asset/Collection/Iterator/AssetSubtypeFilterIterator.php b/core/lib/Drupal/Core/Asset/Collection/Iterator/AssetSubtypeFilterIterator.php
index 5b2c1e5..b7a0395 100644
--- a/core/lib/Drupal/Core/Asset/Collection/Iterator/AssetSubtypeFilterIterator.php
+++ b/core/lib/Drupal/Core/Asset/Collection/Iterator/AssetSubtypeFilterIterator.php
@@ -33,4 +33,4 @@ public function accept() {
     return $this->current()->getAssetType() === $this->match;
   }
 
-}
\ No newline at end of file
+}
diff --git a/core/lib/Drupal/Core/Asset/Collection/Iterator/RecursiveBasicCollectionIterator.php b/core/lib/Drupal/Core/Asset/Collection/Iterator/RecursiveBasicCollectionIterator.php
index 2557a03..f3b83fa 100644
--- a/core/lib/Drupal/Core/Asset/Collection/Iterator/RecursiveBasicCollectionIterator.php
+++ b/core/lib/Drupal/Core/Asset/Collection/Iterator/RecursiveBasicCollectionIterator.php
@@ -21,4 +21,5 @@ public function __construct(AssetCollectionBasicInterface $collection) {
   public function hasChildren() {
     return $this->current() instanceof AssetCollectionBasicInterface;
   }
-}
\ No newline at end of file
+
+}
diff --git a/core/lib/Drupal/Core/Asset/DependencyInterface.php b/core/lib/Drupal/Core/Asset/DependencyInterface.php
index 00488b3..d1d78c7 100644
--- a/core/lib/Drupal/Core/Asset/DependencyInterface.php
+++ b/core/lib/Drupal/Core/Asset/DependencyInterface.php
@@ -21,7 +21,7 @@ public function hasDependencies();
   /**
    * Retrieve this asset's dependencies.
    *
-   * @return mixed
+   * @return array
    *   An array of dependencies if they exist,
    */
   public function getDependencyInfo();
@@ -30,11 +30,11 @@ public function getDependencyInfo();
    * Add a dependency on a library for this asset.
    *
    * @param string $key
-   *   The string identifying the library. It should be two-part composite key,
-   *   slash-delimited, with the first part being the module owner and the
+   *   The string identifying the library. This should be a two-part composite
+   *   key, slash-delimited, with the first part being the module owner and the
    *   second part being the library name.
    *
-   * @return DependencyInterface
+   * @return \Drupal\Core\Asset\DependencyInterface
    *   The current DependencyInterface object.
    */
   public function addDependency($key);
@@ -42,11 +42,12 @@ public function addDependency($key);
   /**
    * Clears (removes) all library dependencies for this asset.
    *
-   * This does not affect ordering data.
+   * This does not affect ordering (relative positioning) data.
    *
-   * @return DependencyInterface
+   * @return \Drupal\Core\Asset\DependencyInterface
    *   The current DependencyInterface object.
    */
   public function clearDependencies();
+
 }
 
diff --git a/core/lib/Drupal/Core/Asset/Exception/AssetTypeMismatchException.php b/core/lib/Drupal/Core/Asset/Exception/AssetTypeMismatchException.php
index ed651bf..16edd41 100644
--- a/core/lib/Drupal/Core/Asset/Exception/AssetTypeMismatchException.php
+++ b/core/lib/Drupal/Core/Asset/Exception/AssetTypeMismatchException.php
@@ -13,4 +13,4 @@
  * For example, if a CSS asset is added to a JS collection, this should be
  * thrown.
  */
-class AssetTypeMismatchException extends \InvalidArgumentException {}
\ No newline at end of file
+class AssetTypeMismatchException extends \InvalidArgumentException {}
diff --git a/core/lib/Drupal/Core/Asset/Exception/FrozenObjectException.php b/core/lib/Drupal/Core/Asset/Exception/FrozenObjectException.php
index ad162d4..6315caa 100644
--- a/core/lib/Drupal/Core/Asset/Exception/FrozenObjectException.php
+++ b/core/lib/Drupal/Core/Asset/Exception/FrozenObjectException.php
@@ -11,4 +11,4 @@
  * Exception thrown when a write-protected operation is attempted on a frozen
  * object.
  */
-class FrozenObjectException extends \LogicException {}
\ No newline at end of file
+class FrozenObjectException extends \LogicException {}
diff --git a/core/lib/Drupal/Core/Asset/Exception/UnsupportedAsseticBehaviorException.php b/core/lib/Drupal/Core/Asset/Exception/UnsupportedAsseticBehaviorException.php
index c25473c..c09b571 100644
--- a/core/lib/Drupal/Core/Asset/Exception/UnsupportedAsseticBehaviorException.php
+++ b/core/lib/Drupal/Core/Asset/Exception/UnsupportedAsseticBehaviorException.php
@@ -11,4 +11,4 @@
  * Assetic supports certain interactions with methods that we do not. This
  * exception is thrown when such methods are touched.
  */
-class UnsupportedAsseticBehaviorException extends \LogicException {}
\ No newline at end of file
+class UnsupportedAsseticBehaviorException extends \LogicException {}
diff --git a/core/lib/Drupal/Core/Asset/ExternalAsset.php b/core/lib/Drupal/Core/Asset/ExternalAsset.php
index bb21da6..7e50611 100644
--- a/core/lib/Drupal/Core/Asset/ExternalAsset.php
+++ b/core/lib/Drupal/Core/Asset/ExternalAsset.php
@@ -14,22 +14,29 @@
 
 class ExternalAsset extends BaseAsset {
 
+  /**
+   * The URL of the asset.
+   *
+   * @var string
+   */
   protected $sourceUrl;
 
   /**
    * Creates a new external asset object.
    *
-   * @param AssetMetadataInterface $metadata
+   * @param \Drupal\Core\Asset\Metadata\AssetMetadataInterface $metadata
    *   The metadata object for the new external asset.
    * @param array $sourceUrl
    *   The URL at which the external asset lives.
-   * @param FilterInterface[] $filters
+   * @param \Assetic\Filter\FilterInterface[] $filters
    *   (optional) An array of FilterInterface objects to apply to this asset.
    *
    * @throws \InvalidArgumentException
    *   Thrown if an invalid URL is provided for $sourceUrl.
    */
   public function __construct(AssetMetadataInterface $metadata, $sourceUrl, $filters = array()) {
+    // Protocol- and root-relative URLs are not acceptable, because such an
+    // asset would not actually be external to this Drupal site.
     if (FALSE === strpos($sourceUrl, '://')) {
       throw new \InvalidArgumentException(sprintf('"%s" is not a valid URL.', $sourceUrl));
     }
diff --git a/core/lib/Drupal/Core/Asset/Factory/AssetCollector.php b/core/lib/Drupal/Core/Asset/Factory/AssetCollector.php
index e50a002..d35a5e1 100644
--- a/core/lib/Drupal/Core/Asset/Factory/AssetCollector.php
+++ b/core/lib/Drupal/Core/Asset/Factory/AssetCollector.php
@@ -5,6 +5,7 @@
  */
 
 namespace Drupal\Core\Asset\Factory;
+
 use Drupal\Core\Asset\AssetInterface;
 use Drupal\Core\Asset\Collection\AssetCollectionInterface;
 use Drupal\Core\Asset\Exception\LockedObjectException;
@@ -51,7 +52,7 @@ class AssetCollector implements AssetCollectorInterface {
   /**
    * The factory that creates metadata bags for assets.
    *
-   * @var MetadataFactoryInterface
+   * @var \Drupal\Core\Asset\Metadata\MetadataFactoryInterface
    */
   protected $metadataFactory;
 
@@ -61,7 +62,7 @@ class AssetCollector implements AssetCollectorInterface {
    * This is used to conveniently create sequencing relationships between CSS
    * assets as they pass through the collector.
    *
-   * @var AssetInterface
+   * @var \Drupal\Core\Asset\AssetInterface
    */
   protected $lastCss;
 
@@ -246,5 +247,5 @@ public function restoreDefaults() {
 
     $this->metadataFactory = new DefaultAssetMetadataFactory();
   }
-}
 
+}
diff --git a/core/lib/Drupal/Core/Asset/Factory/AssetCollectorInterface.php b/core/lib/Drupal/Core/Asset/Factory/AssetCollectorInterface.php
index f171de1..5664f51 100644
--- a/core/lib/Drupal/Core/Asset/Factory/AssetCollectorInterface.php
+++ b/core/lib/Drupal/Core/Asset/Factory/AssetCollectorInterface.php
@@ -53,8 +53,8 @@ public function add(AssetInterface $asset);
    *      A string containing data that defines the asset. Appropriate values vary
    *      depending on the source_type param:
    *      - 'file': the relative path to the file, or a stream wrapper URI.
-   *      - 'external': the absolute path to the external asset.
-   *      - 'string': a string containing valid CSS or Javascript to be injected
+   *      - 'external': the URL to the external asset.
+   *      - 'string': a string containing valid CSS or JavaScript to be injected
    *      directly onto the page.
    * @param array $options
    *      (optional) An array of metadata to explicitly set on the asset. These
@@ -68,6 +68,7 @@ public function add(AssetInterface $asset);
    *      ordering purposes. Only applies to CSS. Note that passing FALSE will not
    *      prevent a CSS asset that is being created from automatically being
    *      after() the existing lastCss asset, if one exists. For that,
+   *      TODO finish this comment
    *
    * @see clearLastCss().
    *
@@ -214,13 +215,15 @@ public function setMetadataFactory(MetadataFactoryInterface $factory);
   public function getMetadataDefaults($asset_type, $source_type, $data);
 
   /**
-   * Restores metadata default bags to their default state.
+   * Restores metadata factory to the default factory.
    *
-   * This simply creates new instances of CssMetadataBag and JsMetadataBag, as
-   * those classes have the normal defaults as hardmapped properties.
+   * This simply changes the metadata factory to
+   * \Drupal\Core\Asset\Metadata\DefaultAssetMetadataFactory, which will cause
+   * future create() calls to use the default metadata.
    *
-   * @throws LockedObjectException
+   * @throws \Drupal\Core\Asset\Exception\LockedObjectException
    *   Thrown if the incorrect key is provided.
    */
   public function restoreDefaults();
-}
\ No newline at end of file
+
+}
diff --git a/core/lib/Drupal/Core/Asset/FileAsset.php b/core/lib/Drupal/Core/Asset/FileAsset.php
index f661ddc..2d65ad6 100644
--- a/core/lib/Drupal/Core/Asset/FileAsset.php
+++ b/core/lib/Drupal/Core/Asset/FileAsset.php
@@ -24,18 +24,18 @@ class FileAsset extends BaseAsset {
   /**
    * Creates a new file asset object.
    *
-   * @param AssetMetadataInterface $metadata
+   * @param \Drupal\Core\Asset\Metadata\AssetMetadataInterface $metadata
    *   The metadata object for the new file asset.
    * @param array $source
-   *   The path at which the external asset lives. This should be the path
-   *   relative to DRUPAL_ROOT, not an absolute path.
-   * @param FilterInterface[] $filters
+   *   The path at which the file asset lives. This should be the path relative
+   *   to DRUPAL_ROOT, not an absolute path.
+   * @param \Assetic\Filter\FilterInterface[] $filters
    *   (optional) An array of FilterInterface objects to apply to this asset.
    *
    * TODO https://drupal.org/node/1308152 would make $source MUCH clearer
    *
    * @throws \InvalidArgumentException
-   *   Thrown if an invalid URL is provided for $sourceUrl.
+   *   Thrown if an invalid URL is provided for $source.
    */
   public function __construct(AssetMetadataInterface $metadata, $source, $filters = array()) {
     if (!is_string($source)) {
@@ -78,4 +78,5 @@ public function load(FilterInterface $additionalFilter = NULL) {
 
     $this->doLoad(file_get_contents($this->source), $additionalFilter);
   }
+
 }
diff --git a/core/lib/Drupal/Core/Asset/GroupSort/AssetGraphSorter.php b/core/lib/Drupal/Core/Asset/GroupSort/AssetGraphSorter.php
index 3aecc1c..ab716ca 100644
--- a/core/lib/Drupal/Core/Asset/GroupSort/AssetGraphSorter.php
+++ b/core/lib/Drupal/Core/Asset/GroupSort/AssetGraphSorter.php
@@ -19,11 +19,18 @@
   /**
    * Creates a queue of starting vertices that will facilitate an ideal TSL.
    *
-   * @param AssetGraph $graph
+   * As a strategy, we assume that the source vertices (tops of the trees
+   * embedded in the graph) that have the greatest reach (and hence would result
+   * in the largest "asset groups") will be the best starting points for
+   * building asset groups: we assume they are more stable and yield the minimal
+   * number of asset groups overall.
+   *
+   * @param \Drupal\Core\Asset\AssetGraph $graph
    *   The graph from which to create a starting queue.
    *
    * @return \SplQueue $queue
-   *   A queue of vertices for traversal.
+   *   A queue of vertices for traversal, the first one being the one with the
+   *   greatest reach.
    */
   protected function createSourceQueue(AssetGraph $graph) {
     $reach_visitor = new DepthFirstBasicVisitor();
@@ -50,4 +57,4 @@ protected function createSourceQueue(AssetGraph $graph) {
     return $queue;
   }
 
-}
\ No newline at end of file
+}
diff --git a/core/lib/Drupal/Core/Asset/GroupSort/AssetGroupSorterInterface.php b/core/lib/Drupal/Core/Asset/GroupSort/AssetGroupSorterInterface.php
index eeb771c..cd7d74d 100644
--- a/core/lib/Drupal/Core/Asset/GroupSort/AssetGroupSorterInterface.php
+++ b/core/lib/Drupal/Core/Asset/GroupSort/AssetGroupSorterInterface.php
@@ -6,6 +6,7 @@
  */
 
 namespace Drupal\Core\Asset\GroupSort;
+
 use Drupal\Core\Asset\AssetInterface;
 use Drupal\Core\Asset\Collection\AssetCollectionInterface;
 
@@ -19,12 +20,12 @@
    *
    * Accounts for dependency and ordering metadata.
    *
-   * @param AssetCollectionInterface $collection
+   * @param \Drupal\Core\Asset\Collection\AssetCollectionInterface $collection
    *   The collection to group and sort.
    *
    * @return array
-   *   A sorted, linear list of assets that respects all necessary dependency
-   *   information.
+   *   A sorted, linear list of assets that respects all dependency and ordering
+   *   metadata.
    */
   public function groupAndSort(AssetCollectionInterface $collection);
 
@@ -34,7 +35,7 @@ public function groupAndSort(AssetCollectionInterface $collection);
    * Assets with the same grouping key are in alignment, meaning that they can
    * be safely aggregated together into a single, composite asset.
    *
-   * @param AssetInterface $asset
+   * @param \Drupal\Core\Asset\AssetInterface $asset
    *   The asset for which to produce a grouping key.
    *
    * @return string|FALSE
@@ -42,4 +43,5 @@ public function groupAndSort(AssetCollectionInterface $collection);
    *   ineligible for grouping.
    */
   public static function getGroupingKey(AssetInterface $asset);
-}
\ No newline at end of file
+
+}
diff --git a/core/lib/Drupal/Core/Asset/GroupSort/CssGraphSorter.php b/core/lib/Drupal/Core/Asset/GroupSort/CssGraphSorter.php
index 50ab63e..a1e0663 100644
--- a/core/lib/Drupal/Core/Asset/GroupSort/CssGraphSorter.php
+++ b/core/lib/Drupal/Core/Asset/GroupSort/CssGraphSorter.php
@@ -94,7 +94,13 @@ public function groupAndSort(AssetCollectionInterface $collection) {
       $optimal_lookup->attach($asset, $optimal[$k]);
     }
 
-    // First, transpose the graph in order to get an appropriate answer
+    // First, transpose the graph in order to get an appropriate answer.
+    // (In the AssetGraph, if asset A comes before asset B, a directed edge
+    // exists from B to A. By transposing the graph, all directed edges are
+    // reversed, so that a directed edge exists from A to B.
+    // A topological sort on a graph will provide a linear ordering of all
+    // vertices, in our example: "A, B". Without performing the transpose
+    // operation, we'd get "B, A", which is the inverse of what we need.)
     $transpose = $graph->transpose();
 
     // Create a queue of start vertices to prime the traversal.
@@ -108,4 +114,5 @@ public function groupAndSort(AssetCollectionInterface $collection) {
     $final->reverse();
     return $final;
   }
-}
\ No newline at end of file
+
+}
diff --git a/core/lib/Drupal/Core/Asset/GroupSort/OptimallyGroupedTSLVisitor.php b/core/lib/Drupal/Core/Asset/GroupSort/OptimallyGroupedTSLVisitor.php
index c34f7c1..9b46e25 100644
--- a/core/lib/Drupal/Core/Asset/GroupSort/OptimallyGroupedTSLVisitor.php
+++ b/core/lib/Drupal/Core/Asset/GroupSort/OptimallyGroupedTSLVisitor.php
@@ -6,6 +6,7 @@
  */
 
 namespace Drupal\Core\Asset\GroupSort;
+
 use Drupal\Core\Asset\Collection\AssetCollection;
 use Gliph\Visitor\DepthFirstVisitorInterface;
 
@@ -107,10 +108,11 @@ public function onFinishVertex($vertex, \Closure $visit) {
   /**
    * Returns the TSL produced by a depth-first traversal.
    *
-   * @return AssetCollection
+   * @return \Drupal\Core\Asset\Collection\AssetCollection
    *   A topologically sorted list of vertices.
    */
   public function getTSL() {
     return $this->tsl;
   }
-}
\ No newline at end of file
+
+}
diff --git a/core/lib/Drupal/Core/Asset/Metadata/AssetMetadataBag.php b/core/lib/Drupal/Core/Asset/Metadata/AssetMetadataBag.php
index 37f2e08..7de5fd1 100644
--- a/core/lib/Drupal/Core/Asset/Metadata/AssetMetadataBag.php
+++ b/core/lib/Drupal/Core/Asset/Metadata/AssetMetadataBag.php
@@ -6,6 +6,7 @@
  */
 
 namespace Drupal\Core\Asset\Metadata;
+
 use Symfony\Component\HttpFoundation\ParameterBag;
 
 /**
@@ -33,4 +34,5 @@ public function __construct($type, array $values = array()) {
   public function getType() {
     return $this->type;
   }
-}
\ No newline at end of file
+
+}
diff --git a/core/lib/Drupal/Core/Asset/Metadata/AssetMetadataInterface.php b/core/lib/Drupal/Core/Asset/Metadata/AssetMetadataInterface.php
index e8eded6..1f77f65 100644
--- a/core/lib/Drupal/Core/Asset/Metadata/AssetMetadataInterface.php
+++ b/core/lib/Drupal/Core/Asset/Metadata/AssetMetadataInterface.php
@@ -79,4 +79,5 @@ public function replace(array $values = array());
    * @return mixed
    */
   public function get($key);
-}
\ No newline at end of file
+
+}
diff --git a/core/lib/Drupal/Core/Asset/Metadata/DefaultAssetMetadataFactory.php b/core/lib/Drupal/Core/Asset/Metadata/DefaultAssetMetadataFactory.php
index e4e44cb..7c32f90 100644
--- a/core/lib/Drupal/Core/Asset/Metadata/DefaultAssetMetadataFactory.php
+++ b/core/lib/Drupal/Core/Asset/Metadata/DefaultAssetMetadataFactory.php
@@ -41,4 +41,5 @@ public function createJsMetadata($source_type, $data) {
       'browsers' => array(),
     ));
   }
-}
\ No newline at end of file
+
+}
diff --git a/core/lib/Drupal/Core/Asset/Metadata/MetadataFactoryInterface.php b/core/lib/Drupal/Core/Asset/Metadata/MetadataFactoryInterface.php
index 9e3eb30..0e3b866 100644
--- a/core/lib/Drupal/Core/Asset/Metadata/MetadataFactoryInterface.php
+++ b/core/lib/Drupal/Core/Asset/Metadata/MetadataFactoryInterface.php
@@ -11,6 +11,7 @@
  * Interface for factories that create asset metadata.
  */
 interface MetadataFactoryInterface {
+
   /**
    * Creates an asset metadata object for use in a CSS AssetInterface object.
    *
@@ -22,7 +23,7 @@
    *   For 'file' or 'external' source types, this is the path to the asset. For
    *   'string' source types, it is the whole body of the asset.
    *
-   * @return AssetMetadataInterface
+   * @return \Drupal\Core\Asset\Metadata\AssetMetadataInterface
    */
   public function createCssMetadata($source_type, $data);
 
@@ -37,7 +38,8 @@ public function createCssMetadata($source_type, $data);
    *   For 'file' or 'external' source types, this is the path to the asset. For
    *   'string' source types, it is the whole body of the asset.
    *
-   * @return AssetMetadataInterface
+   * @return \Drupal\Core\Asset\Metadata\AssetMetadataInterface
    */
   public function createJsMetadata($source_type, $data);
-}
\ No newline at end of file
+
+}
diff --git a/core/lib/Drupal/Core/Asset/RelativePositionInterface.php b/core/lib/Drupal/Core/Asset/RelativePositionInterface.php
index cd6c6e0..fa49ab7 100644
--- a/core/lib/Drupal/Core/Asset/RelativePositionInterface.php
+++ b/core/lib/Drupal/Core/Asset/RelativePositionInterface.php
@@ -7,7 +7,7 @@
 namespace Drupal\Core\Asset;
 
 /**
- * Describes an asset or asset-like object that can declare dependencies.
+ * Describes an asset or asset-like object that can declare relative positions.
  */
 interface RelativePositionInterface {
 
@@ -17,10 +17,10 @@
    * Either the string identifier for the other asset, or the asset object
    * itself, should be provided.
    *
-   * @param string|AssetInterface $asset
+   * @param string|\Drupal\Core\Asset\AssetInterface $asset
    *   The asset to precede the current asset.
    *
-   * @return RelativePositionInterface
+   * @return \Drupal\Core\Asset\RelativePositionInterface
    *   The current RelativePositionInterface object.
    */
   public function after($asset);
@@ -46,7 +46,7 @@ public function getPredecessors();
    *
    * This does not affect dependency data.
    *
-   * @return RelativePositionInterface
+   * @return \Drupal\Core\Asset\RelativePositionInterface
    *   The current RelativePositionInterface object.
    */
   public function clearPredecessors();
@@ -57,10 +57,10 @@ public function clearPredecessors();
    * Either the string identifier for the other asset, or the asset object
    * itself, should be provided.
    *
-   * @param string|AssetInterface $asset
+   * @param string|\Drupal\Core\Asset\AssetInterface $asset
    *   The asset to succeed the current asset.
    *
-   * @return RelativePositionInterface
+   * @return \Drupal\Core\Asset\RelativePositionInterface
    *   The current RelativePositionInterface object.
    */
   public function before($asset);
@@ -86,7 +86,7 @@ public function getSuccessors();
    *
    * This does not affect dependency data.
    *
-   * @return RelativePositionInterface
+   * @return \Drupal\Core\Asset\RelativePositionInterface
    *   The current RelativePositionInterface object.
    */
   public function clearSuccessors();
diff --git a/core/lib/Drupal/Core/Asset/StringAsset.php b/core/lib/Drupal/Core/Asset/StringAsset.php
index eb54094..8c1488f 100644
--- a/core/lib/Drupal/Core/Asset/StringAsset.php
+++ b/core/lib/Drupal/Core/Asset/StringAsset.php
@@ -29,11 +29,11 @@ class StringAsset extends BaseAsset {
   /**
    * Creates a new string asset object.
    *
-   * @param AssetMetadataInterface $metadata
+   * @param \Drupal\Core\Asset\Metadata\AssetMetadataInterface $metadata
    *   The metadata object for the new string asset.
    * @param string $content
-   *   The content of the new asset.
-   * @param FilterInterface[] $filters
+   *   The content of the new string asset.
+   * @param \Assetic\Filter\FilterInterface[] $filters
    *   (optional) An array of FilterInterface objects to apply to this asset.
    *
    * @throws \InvalidArgumentException
@@ -57,15 +57,25 @@ public function id() {
     return $this->id;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function setLastModified($last_modified) {
     $this->lastModified = $last_modified;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function getLastModified() {
     return $this->lastModified;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function load(FilterInterface $additionalFilter = NULL) {
     $this->doLoad($this->getContent(), $additionalFilter);
   }
+
 }