[symfony#2913] Minor tweaks to the built-out class loader component docs by @xabbuh

weaverryan · weaverryan · commit 8a8682f1d055 · 2013-09-28T17:51:13.000-05:00
diff --git a/book/performance.rst b/book/performance.rst
@@ -88,6 +88,8 @@ as comments in this file::
 
     // ...
 
+For more details, see :doc:`/components/class_loader/cache_class_loader`.
+
 .. note::
 
     When using the APC autoloader, if you add new classes, they will be found
diff --git a/components/class_loader/cache_class_loader.rst b/components/class_loader/cache_class_loader.rst
@@ -34,7 +34,7 @@ ApcClassLoader
 
     require_once '/path/to/src/Symfony/Component/ClassLoader/ApcClassLoader.php';
     
-    // instance of a class that implements a findFile() method
+    // instance of a class that implements a findFile() method, like the ClassLoader
     $loader = ...;
     
     // my_prefix is the APC namespace prefix to use
@@ -43,8 +43,7 @@ ApcClassLoader
     // register the cached class loader
     $cachedLoader->register();
     
-    // eventually deactivate the non-cached loader if it was registered
-    // previously
+    // deactivate the original, non-cached loader if it was registered previously
     $loader->unregister();
 
 XcacheClassLoader
@@ -58,7 +57,7 @@ it is straightforward::
 
     require_once '/path/to/src/Symfony/Component/ClassLoader/XcacheClassLoader.php';
     
-    // instance of a class that implements a findFile() method
+    // instance of a class that implements a findFile() method, like the ClassLoader
     $loader = ...;
     
     // my_prefix is the XCache namespace
@@ -67,8 +66,7 @@ it is straightforward::
     // register the cached class loader
     $cachedLoader->register();
     
-    // eventually deactivate the non-cached loader if it was registered
-    // previously
+    // deactivate the original, non-cached loader if it was registered previously
     $loader->unregister();
 
 .. _APC:        http://php.net/manual/en/book.apc.php
diff --git a/components/class_loader/class_loader.rst b/components/class_loader/class_loader.rst
@@ -4,13 +4,10 @@
 The PSR-0 Class Loader
 ======================
 
-Introduction
-------------
-
 .. versionadded:: 2.1
     The ``ClassLoader`` class was added in Symfony 2.1.
 
-If your classes and third-party libraries follow the `PSR-0`_ standards, you
+If your classes and third-party libraries follow the `PSR-0`_ standard, you
 can use the :class:`Symfony\\Component\\ClassLoader\\ClassLoader` class to
 load all of your project's classes.
 
@@ -79,9 +76,9 @@ projects::
 
 In this example, if you try to use a class in the ``Doctrine\Common`` namespace
 or one of its children, the autoloader will first look for the class under the
-``doctrine-common`` directory, and it will then fallback to the default
-``Doctrine`` directory (the last one configured) if not found, before giving up.
-The order of the registrations is significant in this case.
+``doctrine-common`` directory. If not found, it will then fallback to the default
+``Doctrine`` directory (the last one configured) before giving up. The order
+of the prefix registrations is significant in this case.
 
 .. _PEAR:  http://pear.php.net/manual/en/standards.naming.php
 .. _PSR-0: http://symfony.com/PSR0
diff --git a/components/class_loader/debug_class_loader.rst b/components/class_loader/debug_class_loader.rst
@@ -7,14 +7,13 @@ Debugging a Class Loader
 .. versionadded:: 2.1
     The ``DebugClassLoader`` class was added in Symfony 2.1.
 
-When a class isn't found by the registered autoloaders you can use the
-:class:`Symfony\\Component\\ClassLoader\\DebugClassLoader`. All autoloaders
-which implement a ``findFile()`` method are replaced with a ``DebugClassLoader``
-wrapper. It throws an exception if a file is found but does not declare the
-class.
+The :class:`Symfony\\Component\\ClassLoader\\DebugClassLoader` attempts to
+throw more helpful exceptions when a class isn't found by the registered
+autoloaders. All autoloaders that implement a ``findFile()`` method are replaced
+with a ``DebugClassLoader`` wrapper.
 
-Using the ``DebugClassLoader`` is as easy as calling its static :method:`DebugClassLoader::enable`
-method::
+Using the ``DebugClassLoader`` is as easy as calling its static
+:method:`Symfony\\Component\\ClassLoader\\DebugClassLoader::enable` method::
 
     use Symfony\Component\ClassLoader\DebugClassLoader;
     
diff --git a/components/class_loader/introduction.rst b/components/class_loader/introduction.rst
@@ -4,18 +4,21 @@
 The Class Loader Component
 ==========================
 
-    The Class Loader Component provides tools to load and cache your project
-    classes automatically.
+    The Class Loader Component provides tools to autoload your classes and
+    cache their locations for performance.
 
 Usage
 -----
 
-Whenever you use an undefined class, PHP uses the autoloading mechanism to
-delegate the loading of a file defining the class. Symfony2 provides two
-autoloaders, which are able to load your classes:
+Whenever you reference a class that has not been required or included yet,
+PHP uses the `autoloading mechanism`_ to delegate the loading of a file defining
+the class. Symfony2 provides two autoloaders, which are able to load your classes:
 
-* :doc:`A PSR-0 class loader </components/class_loader/class_loader>`
-* :doc:`Load classes based on class-to-file mapping </components/class_loader/map_class_loader>`
+* :doc:`/components/class_loader/class_loader`: loads classes that follow
+  the `PSR-0` class naming standard;
+
+* :doc:`/components/class_loader/map_class_loader`: loads classes using
+  a static map from class name to file path.
 
 Additionally, the Symfony Class Loader Component ships with a set of wrapper
 classes which can be used to add additional functionality on top of existing
@@ -33,4 +36,5 @@ You can install the component in 2 different ways:
 * :doc:`Install it via Composer </components/using_components>` (``symfony/class-loader``
   on `Packagist`_).
 
+.. _`autoloading mechanism`: http://php.net/manual/en/language.oop5.autoload.php
 .. _Packagist: https://packagist.org/packages/symfony/class-loader
diff --git a/components/class_loader/map_class_loader.rst b/components/class_loader/map_class_loader.rst
@@ -4,14 +4,20 @@
 MapClassLoader
 ==============
 
-Introduction
-------------
+The :class:`Symfony\\Component\\ClassLoader\\MapClassLoader` allows you to
+autoload files via a static map from classes to files. This is useful if you
+use third-party libraries which don't follow the `PSR-0`_ standards and so
+can't use the :doc:`PSR-0 class loader </components/class_loader/class_loader>`.
 
-Additionally to any dynamic class loader (like the
-:doc:`PSR-0 class loader </components/class_loader/class_loader>`) you can use
-the :class:`Symfony\\Component\\ClassLoader\\MapClassLoader` to statically map
-classes to files. This is useful if you use third-party libraries which don't
-follow the `PSR-0`_ standards.
+The ``MapClassLoader`` can be used along with the :doc:`PSR-0 class loader </components/class_loader/class_loader>`
+by configuring and calling the ``register()`` method on both.
+
+.. note::
+
+    The default behavior is to append the ``MapClassLoader`` on the autoload
+    stack. If you want to use it as the first autoloader, pass ``true`` when
+    calling the ``register()`` method. Your class loader will then be prepended
+    on the autoload stack.
 
 Usage
 -----
@@ -29,12 +35,5 @@ an instance of the ``MapClassLoader`` class::
     $loader = new MapClassLoader($mapping);
     
     $loader->register();
-    
-.. note::
-
-    The default behavior is to append the ``MapClassLoader`` on the autoload
-    stack. If you want to use it as the default autoloader, pass ``true``
-    when calling the ``register()`` method. Your class loader will then be
-    prepended on the autoload stack.
 
 .. _PSR-0: http://symfony.com/PSR0
