diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 1fe027c..8af5387 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -704,19 +704,21 @@
 /**
  * @defgroup container Services and Dependency Injection Container
  * @{
- * Information about the Dependency Injection Container and Services.
+ * Overview of the Dependency Injection Container and Services.
  *
  * @section sec_overview Overview of container, injection, and services
  * The Services and Dependency Injection Container concepts have been adopted by
  * Drupal from the @link http://symfony.com/ Symfony framework. @endlink A
  * "service" (such as accessing the database, sending email, or translating user
- * interface text) can be defined by Drupal Core or a module, along with a
- * default class for providing that service. Other modules can offer alternative
- * classes to provide the same services, overriding the default classes. Classes
- * and functions that need to use the service should always instantiate the
- * class via the "dependency injection container" (also known simply as the
- * "container"), rather than instantiating a particular service provider class
- * directly, so that they get the correct class (default or overridden).
+ * interface text) is defined (given an name and an interface), and a default
+ * class is defined to provide the service. These two steps must be done
+ * together, and can be done by Drupal Core or a module. Other modules can then
+ * define alternative classes to provide the same services, overriding the
+ * default classes. Classes and functions that need to use the service should
+ * always instantiate the class via the dependency injection container (also
+ * known simply as the "container"), rather than instantiating a particular
+ * service provider class directly, so that they get the correct class
+ * (default or overridden).
  *
  * See https://drupal.org/node/2133171 for more detailed information on
  * services and the dependency injection container.
@@ -728,23 +730,26 @@
  * (such as https://api.drupal.org) generate lists of all existing services from
  * these files, or you can look through the individual files manually.
  *
- * A typical service definition in a services.yml file looks like this:
+ * A typical service definition in a *.services.yml file looks like this:
  * @code
  * path.alias_manager:
  *   class: Drupal\Core\Path\AliasManager
  *   arguments: ['@path.crud', '@path.alias_whitelist', '@language_manager']
  * @endcode
- * The first line gives the machine name of the service, and the class line
+ * The first line gives the unique machine name of the service (typically
+ * prefixed by the module name if provided by a module), and the class line
  * gives the default class that provides the service. For some services, the
- * arguments line lists other services that are dependencies; the classes
- * for each of these services is instantiated from the container and passed
- * to the class constructor when the service class is instantiated.
+ * arguments line lists the machine names of other services that are
+ * dependencies (preceded by '@'); objects for each of these services are
+ * instantiated from the container and passed to the class constructor when the
+ * service class is instantiated. Other arguments can also be passed in; see
+ * the section at https://drupal.org/node/2133171 for more detailed information.
  *
  * @section sec_container Accessing a service through the container
  * As noted above, if you need to use a service in your code, you should always
- * instantiate the service class via a call to the container, so that the
- * default class can be overridden. There are several ways to make sure this
- * happens:
+ * instantiate the service class via a call to the container, using the machine
+ * name of the service, so that the default class can be overridden. There are
+ * several ways to make sure this happens:
  * - For service-providing classes, see other sections of this documentation
  *   describing how to pass services as arguments to the constructor.
  * - Plugin classes, controllers, and similar classes have create() methods,
@@ -753,18 +758,18 @@
  *   \Symfony\Component\DependencyInjection\ContainerInterface $container
  *   @endcode
  *   In the create() method, call
- *   @code $container->get('service.name') @endcode to instantiate a service.
+ *   @code $container->get('myservice.name') @endcode to instantiate a service.
  *   The results of these calls are generally passed to the class constructor
  *   and saved as member variables in the class.
  * - For functions and class methods that do not have access to either of
- *   the above methods of "dependency injection", you can access the container
+ *   the above methods of dependency injection, you can access the container
  *   via a call to the global \Drupal class. This class has special methods for
  *   accessing commonly-used services, or you can call a generic method to
  *   access any service. Examples:
  *   @code
- *   // Retrieve the entity.manager service class (special method exists).
+ *   // Retrieve the entity.manager service object (special method exists).
  *   $manager = \Drupal->entityManager();
- *   // Retrieve the foo.bar service class (no special method exists).
+ *   // Retrieve the service object for machine name 'foo.bar'.
  *   $foobar = \Drupal->service('foo.bar');
  *   @endcode
  *