diff --git a/core/lib/Drupal/Component/Datetime/DateTimePlus.php b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
index 907420b..52732b9 100644
--- a/core/lib/Drupal/Component/Datetime/DateTimePlus.php
+++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php
@@ -7,9 +7,9 @@
 namespace Drupal\Component\Datetime;
 
 /**
- * This class is an extension of the PHP DateTime class.
+ * Extends DateTime().
  *
- * It extends the PHP DateTime class with more flexible initialization
+ * This class extends the PHP DateTime class with more flexible initialization
  * parameters, allowing a date to be created from an existing date object,
  * a timestamp, a string with an unknown format, a string with a known
  * format, or an array of date parts. It also adds an errors array
@@ -34,8 +34,7 @@
  * errors. It has an errors array attached to it that explains what the
  * errors are. This is less disruptive than allowing datetime exceptions
  * to abort processing. The calling script can decide what to do about
- * errors by checking the hasErrors() method and using the messages in
- * the errors array.
+ * errors using hasErrors() and getErrors().
  */
 class DateTimePlus extends \DateTime {
 
@@ -48,13 +47,13 @@ class DateTimePlus extends \DateTime {
    * An array of possible date parts.
    */
   protected static $dateParts = array(
-                              'year',
-                              'month',
-                              'day',
-                              'hour',
-                              'minute',
-                              'second',
-                             );
+                                 'year',
+                                 'month',
+                                 'day',
+                                 'hour',
+                                 'minute',
+                                 'second',
+                                );
 
   /**
    * The value of the time value passed to the constructor.
@@ -123,27 +122,25 @@ class DateTimePlus extends \DateTime {
    *   Defaults to NULL.
    *   @see http://us3.php.net/manual/en/datetime.createfromformat.php
    * @param array $settings
-   *   - boolean $validate_format
-   *     The format used in createFromFormat() allows slightly different
-   *     values than format(). If we use an input format that works in
-   *     both functions we can add a validation step to confirm that the
-   *     date created from a format string exactly matches the input.
-   *     We need to know if this can be relied on to do that validation.
-   *     Defaults to TRUE.
-   *   - string $langcode
-   *     The two letter language code to construct the locale string by the
-   *     intlDateFormatter class. Used to control the result of the
-   *     format() method if that class is available. Defaults to NULL.
-   *   - string $country
-   *     The two letter country code to construct the locale string by the
-   *     intlDateFormatter class. Used to control the result of the
-   *     format() method if that class is available. Defaults to NULL.
-   *   - string $calendar
-   *     A calendar name to use for the date, Defaults to
-   *     DateTimePlus::CALENDAR.
-   *   - boolean $debug
-   *     Leave evidence of the input values in the resulting object
-   *     for debugging purposes. Defaults to FALSE.
+   *   - validate_format: (optional) Boolean choice to validate the
+   *     created date using the input format. The format used in
+   *     createFromFormat() allows slightly different values than format().
+   *     Using an input format that works in both functions makes it
+   *     possible to a validation step to confirm that the date created
+   *     from a format string exactly matches the input. This option
+   *     indicates the format can be used for validation. Defaults to TRUE.
+   *   - langcode: (optional) String two letter language code to construct
+   *     the locale string by the intlDateFormatter class. Used to control
+   *     the result of the format() method if that class is available.
+   *     Defaults to NULL.
+   *   - country: (optional) String two letter country code to construct
+   *     the locale string by the intlDateFormatter class. Used to control
+   *     the result of the format() method if that class is available.
+   *     Defaults to NULL.
+   *   - calendar: (optional) String calendar name to use for the date.
+   *     Defaults to DateTimePlus::CALENDAR.
+   *   - debug: (optional) Boolean choice to leave debug values in the
+   *     date object for debugging purposes. Defaults to FALSE.
    */
   public function __construct($time = 'now', $timezone = NULL, $format = NULL, $settings = array()) {
 
@@ -208,11 +205,12 @@ public function __construct($time = 'now', $timezone = NULL, $format = NULL, $se
   }
 
   /**
-   * Implementation of __toString() for dates. The base DateTime
-   * class does not implement this.
+   * Implements __toString() for dates.
    *
-   * @see https://bugs.php.net/bug.php?id=62911 and
-   * http://www.serverphorums.com/read.php?7,555645
+   * The base DateTime class does not implement this.
+   *
+   * @see https://bugs.php.net/bug.php?id=62911
+   * @see http://www.serverphorums.com/read.php?7,555645
    */
   public function __toString() {
     $format = static::FORMAT;
@@ -220,20 +218,24 @@ public function __toString() {
   }
 
   /**
-   * Prepare the input value before trying to use it.
+   * Prepares the input time value.
+   *
+   * Changes the input value before trying to use it, if necessary.
    * Can be overridden to handle special cases.
    *
    * @param mixed $time
    *   An input value, which could be a timestamp, a string,
-   *   a date object, or an array of date parts.
+   *   or an array of date parts.
    */
   protected function prepareTime($time) {
     $this->inputTimeAdjusted = $time;
   }
 
   /**
-   * Prepare the timezone before trying to use it.
-   * Most imporantly, make sure we have a valid timezone
+   * Prepares the input timezone value.
+   *
+   * Changes the timezone before trying to use it, if necessary.
+   * Most imporantly, makes sure there is a valid timezone
    * object before moving further.
    *
    * @param mixed $timezone
@@ -269,7 +271,9 @@ protected function prepareTimezone($timezone) {
   }
 
   /**
-   * Prepare the input format before trying to use it.
+   * Prepares the input format value.
+   *
+   * Changes the input format before trying to use it, if necessary.
    * Can be overridden to handle special cases.
    *
    * @param string $format
@@ -280,7 +284,7 @@ protected function prepareFormat($format) {
   }
 
   /**
-   * Check if input is a DateTime object.
+   * Checks whether input is a DateTime object.
    *
    * @return boolean
    *   TRUE if the input time is a DateTime object.
@@ -290,7 +294,7 @@ public function inputIsObject() {
   }
 
   /**
-   * Create a date object from an input date object.
+   * Creates a date object from an input date object.
    */
   protected function constructFromObject() {
     try {
@@ -303,7 +307,7 @@ protected function constructFromObject() {
   }
 
   /**
-   * Check if input time seems to be a timestamp.
+   * Checks whether input time seems to be a timestamp.
    *
    * Providing an input format will prevent ISO values without separators
    * from being mis-interpreted as timestamps. Providing a format can also
@@ -318,11 +322,10 @@ public function inputIsTimestamp() {
   }
 
   /**
-   * Create a date object from timestamp input.
+   * Creates a date object from timestamp input.
    *
-   * The timezone for timestamps is always UTC. In this case the
-   * timezone we set controls the timezone used when displaying
-   * the value using format().
+   * The timezone of a timestamp is always UTC. The timezone for a
+   * timestamp indicates the timezone used by the format() method.
    */
   protected function constructFromTimestamp() {
     try {
@@ -335,7 +338,7 @@ protected function constructFromTimestamp() {
   }
 
   /**
-   * Check if input is an array of date parts.
+   * Checks if input is an array of date parts.
    *
    * @return boolean
    *   TRUE if the input time is a DateTime object.
@@ -345,9 +348,9 @@ public function inputIsArray() {
   }
 
   /**
-   * Create a date object from an array of date parts.
+   * Creates a date object from an array of date parts.
    *
-   * Convert the input value into an ISO date, forcing a full ISO
+   * Converts the input value into an ISO date, forcing a full ISO
    * date even if some values are missing.
    */
   protected function constructFromArray() {
@@ -372,7 +375,7 @@ protected function constructFromArray() {
   }
 
   /**
-   * Check if input is a string with an expected format.
+   * Checks if input is a string with an expected format.
    *
    * @return boolean
    *   TRUE if the input time is a string with an expected format.
@@ -382,11 +385,10 @@ public function inputIsFormat() {
   }
 
   /**
-   * Create a date object from an input format.
-   *
+   * Creates a date object from an input format.
    */
   protected function constructFromFormat() {
-    // Try to create a date from the format and use it if possible.
+    // Tries to create a date from the format and use it if possible.
     // A regular try/catch won't work right here, if the value is
     // invalid it doesn't return an exception.
     try {
@@ -422,11 +424,11 @@ protected function constructFromFormat() {
   }
 
   /**
-   * Fallback construction for values that don't match any of the
-   * other patterns.
+   * Creates a date when none of the other methods are appropriate.
    *
-   * Let the parent dateTime attempt to turn this string into a
-   * valid date.
+   * Fallback construction for values that don't match any of the
+   * other patterns. Lets the parent dateTime attempt to turn this string
+   * into a valid date.
    */
   protected function constructFallback() {
 
@@ -453,9 +455,9 @@ protected function constructFallback() {
   }
 
   /**
-   * Examine getLastErrors() and see what errors to report.
+   * Examines getLastErrors() to see what errors to report.
    *
-   * We're interested in two kinds of errors: anything that DateTime
+   * Two kinds of errors are important: anything that DateTime
    * considers an error, and also a warning that the date was invalid.
    * PHP creates a valid date from invalid data with only a warning,
    * 2011-02-30 becomes 2011-03-03, for instance, but we don't want that.
@@ -468,22 +470,25 @@ public function checkErrors() {
       $this->errors += $errors['errors'];
     }
     // Most warnings are messages that the date could not be parsed
-    // which causes it to be altered. We're going to consider a warning
-    // as bad as an error.
+    // which causes it to be altered. For validation purposes, a warning
+    // as bad as an error, because it means the constructed date does
+    // not match the input value.
     if (!empty($errors['warnings'])) {
       $this->errors[] = 'The date is invalid.';
     }
   }
 
   /**
-   * Detect if there were errors in the processing of this date.
+   * Detects if there were errors in the processing of this date.
    */
   public function hasErrors() {
     return (boolean) count($this->errors);
   }
 
   /**
-   * Public function to retrieve the error messages.
+   * Retrieves error messages.
+   *
+   * Public function to return the error messages.
    */
   public function getErrors() {
     return $this->errors;
@@ -565,9 +570,11 @@ public static function prepareArray($array, $force_valid_date = FALSE) {
   }
 
   /**
-   * Check that an array of date parts has a year, month, and day,
+   * Checks that arrays of date parts will create a valid date.
+   *
+   * Checks that an array of date parts has a year, month, and day,
    * and that those values create a valid date. If time is provided,
-   * verify that the time values are valid. Sort of an
+   * verifies that the time values are valid. Sort of an
    * equivalent to checkdate().
    *
    * @param array $array
@@ -611,9 +618,9 @@ public static function checkArray($array) {
   }
 
   /**
-   * Helper function to left pad date parts with zeros.
+   * Pads date parts with zeros.
    *
-   * Provided because this is needed so often with dates.
+   * Helper function for a task that is often required when working with dates.
    *
    * @param int $value
    *   The value to pad.
@@ -629,52 +636,46 @@ public static function datePad($value, $size = 2) {
 
 
   /**
-   * Test if the IntlDateFormatter is available and we have the
-   * right information to be able to use it.
+   * Tests whether the IntlDateFormatter can be used.
    */
   public function canUseIntl() {
     return class_exists('IntlDateFormatter') && !empty($this->calendar) && !empty($this->langcode) && !empty($this->country);
   }
 
   /**
-   * Format the date for display.
+   * Formats the date for display.
    *
-   * Use the IntlDateFormatter to display the format, if possible.
-   * Because the IntlDateFormatter is not always available, we
-   * add an optional array of settings that provides the information
+   * Uses the IntlDateFormatter to display the format, if possible.
+   * Adds an optional array of settings that provides the information
    * the IntlDateFormatter will need.
    *
    * @param string $format
    *   A format string using either PHP's date() or the
    *   IntlDateFormatter() format.
    * @param array $settings
-   *   - string $format_string_type
-   *     Which pattern is used by the format string. When using the
-   *     Intl formatter, the format string must use the Intl pattern,
-   *     which is different from the pattern used by the DateTime
-   *     format function. Defaults to DateTimePlus::PHP.
-   *   - string $timezone
-   *     A timezone name. Defaults to the timezone of the date object.
-   *   - string $langcode
-   *     The two letter language code to construct the locale string by the
-   *     intlDateFormatter class. Used to control the result of the
-   *     format() method if that class is available. Defaults to NULL.
-   *   - string $country
-   *     The two letter country code to construct the locale string by the
-   *     intlDateFormatter class. Used to control the result of the
-   *     format() method if that class is available. Defaults to NULL.
-   *   - string $calendar
-   *     A calendar name to use for the date, Defaults to
-   *     DateTimePlus::CALENDAR.
-   *   - int $date_type
-   *     The date type to use in the formatter, defaults to
-   *     IntlDateFormatter::FULL.
-   *   - int $time_type
-   *     The date type to use in the formatter, defaults to
-   *     IntlDateFormatter::FULL.
-   *   - boolean $lenient
-   *     Whether or not to use lenient processing in the intl
-   *     formatter. Defaults to FALSE;
+   *   - format_string_type: (optional) DateTimePlus::PHP or
+   *     DateTimePlus::INTL. Identifies the pattern used by the format
+   *     string. When using the Intl formatter, the format string must
+   *     use the Intl pattern, which is different from the pattern used
+   *     by the DateTime format function. Defaults to DateTimePlus::PHP.
+   *   - timezone: (optional) String timezone name. Defaults to the timezone
+   *     of the date object.
+   *   - langcode: (optional) String two letter language code to construct the
+   *     locale string by the intlDateFormatter class. Used to control the
+   *     result of the format() method if that class is available. Defaults
+   *     to NULL.
+   *   - country: (optional) String two letter country code to construct the
+   *     locale string by the intlDateFormatter class. Used to control the
+   *     result of the format() method if that class is available. Defaults
+   *     to NULL.
+   *   - calendar: (optional) String calendar name to use for the date,
+   *     Defaults to DateTimePlus::CALENDAR.
+   *   - date_type: (optional) Integer date type to use in the formatter,
+   *     defaults to IntlDateFormatter::FULL.
+   *   - time_type: (optional) Integer date type to use in the formatter,
+   *     defaults to IntlDateFormatter::FULL.
+   *   - lenient: (optional) Boolean choice of whether or not to use lenient
+   *     processing in the intl formatter. Defaults to FALSE;
    *
    * @return string
    *   The formatted value of the date.
@@ -690,7 +691,7 @@ public function format($format, $settings = array()) {
     $langcode = !empty($settings['langcode']) ? $settings['langcode'] : $this->langcode;
     $country = !empty($settings['country']) ? $settings['country'] : $this->country;
     $calendar = !empty($settings['calendar']) ? $settings['calendar'] : $this->calendar;
-    $time_zone = !empty($settings['timezone']) ? $settings['timezone'] : $this->getTimezone()->getName();
+    $timezone = !empty($settings['timezone']) ? $settings['timezone'] : $this->getTimezone()->getName();
     $lenient  = !empty($settings['lenient'])  ? $settings['lenient']  : FALSE;
 
     // Format the date and catch errors.
@@ -715,7 +716,7 @@ public function format($format, $settings = array()) {
 
         $date_type = !empty($settings['date_type']) ? $settings['date_type'] : \IntlDateFormatter::FULL;
         $time_type = !empty($settings['time_type']) ? $settings['time_type'] : \IntlDateFormatter::FULL;
-        $formatter = new \IntlDateFormatter($locale, $date_type, $time_type, $time_zone, $calendar_type);
+        $formatter = new \IntlDateFormatter($locale, $date_type, $time_type, $timezone, $calendar_type);
         $formatter->setLenient($lenient);
         $value = $formatter->format($format);
       }
diff --git a/core/lib/Drupal/Core/Datetime/DrupalDateTime.php b/core/lib/Drupal/Core/Datetime/DrupalDateTime.php
index 6d8b128..775e668 100644
--- a/core/lib/Drupal/Core/Datetime/DrupalDateTime.php
+++ b/core/lib/Drupal/Core/Datetime/DrupalDateTime.php
@@ -9,7 +9,7 @@
 use Drupal\Component\Datetime\DateTimePlus;
 
 /**
- * This class is an extension of the Drupal DateTimePlus class.
+ * Extends DateTimePlus().
  *
  * This class extends the basic component and adds in Drupal-specific
  * handling, like translation of the format() method.
@@ -36,27 +36,25 @@ class DrupalDateTime extends DateTimePlus {
    *   Defaults to NULL.
    *   @see http://us3.php.net/manual/en/datetime.createfromformat.php
    * @param array $settings
-   *   - boolean $validate_format
-   *     The format used in createFromFormat() allows slightly different
-   *     values than format(). If we use an input format that works in
-   *     both functions we can add a validation step to confirm that the
-   *     date created from a format string exactly matches the input.
-   *     We need to know if this can be relied on to do that validation.
-   *     Defaults to TRUE.
-   *   - string $langcode
-   *     The two letter language code to construct the locale string by the
-   *     intlDateFormatter class. Used to control the result of the
-   *     format() method if that class is available. Defaults to NULL.
-   *   - string $country
-   *     The two letter country code to construct the locale string by the
-   *     intlDateFormatter class. Used to control the result of the
-   *     format() method if that class is available. Defaults to NULL.
-   *   - string $calendar
-   *     A calendar name to use for the date, Defaults to
-   *     DateTimePlus::CALENDAR.
-   *   - boolean $debug
-   *     Leave evidence of the input values in the resulting object
-   *     for debugging purposes. Defaults to FALSE.
+   *   - validate_format: (optional) Boolean choice to validate the
+   *     created date using the input format. The format used in
+   *     createFromFormat() allows slightly different values than format().
+   *     Using an input format that works in both functions makes it
+   *     possible to a validation step to confirm that the date created
+   *     from a format string exactly matches the input. This option
+   *     indicates the format can be used for validation. Defaults to TRUE.
+   *   - langcode: (optional) String two letter language code to construct
+   *     the locale string by the intlDateFormatter class. Used to control
+   *     the result of the format() method if that class is available.
+   *     Defaults to NULL.
+   *   - country: (optional) String two letter country code to construct
+   *     the locale string by the intlDateFormatter class. Used to control
+   *     the result of the format() method if that class is available.
+   *     Defaults to NULL.
+   *   - calendar: (optional) String calendar name to use for the date.
+   *     Defaults to DateTimePlus::CALENDAR.
+   *   - debug: (optional) Boolean choice to leave debug values in the
+   *     date object for debugging purposes. Defaults to FALSE.
    */
   public function __construct($time = 'now', $timezone = NULL, $format = NULL, $settings = array()) {
 
@@ -70,6 +68,8 @@ public function __construct($time = 'now', $timezone = NULL, $format = NULL, $se
   }
 
   /**
+   * Overrides prepareTimezone().
+   *
    * Override basic component timezone handling to use Drupal's
    * knowledge of the preferred user timezone.
    */
@@ -82,45 +82,39 @@ protected function prepareTimezone($timezone) {
   }
 
   /**
-   * Format the date for display.
+   * Overrides format().
    *
-   * Use the IntlDateFormatter to display the format, if available.
-   * Because the IntlDateFormatter is not always available, we
-   * need to know whether the $format string uses the standard
-   * format strings used by the date() function or the alternative
-   * format provided by the IntlDateFormatter.
+   * Uses the IntlDateFormatter to display the format, if possible.
+   * Adds an optional array of settings that provides the information
+   * the IntlDateFormatter will need.
    *
    * @param string $format
-   *   A format string using either date() or IntlDateFormatter()
-   *   format.
+   *   A format string using either PHP's date() or the
+   *   IntlDateFormatter() format.
    * @param array $settings
-   *   - string $format_string_type
-   *     Which pattern is used by the format string. When using the
-   *     Intl formatter, the format string must use the Intl pattern,
-   *     which is different from the pattern used by the DateTime
-   *     format function. Defaults to DateTimePlus::PHP.
-   *   - string $timezone
-   *     A timezone name. Defaults to the timezone of the date object.
-   *   - string $langcode
-   *     The two letter language code to construct the locale string by the
-   *     intlDateFormatter class. Used to control the result of the
-   *     format() method if that class is available. Defaults to NULL.
-   *   - string $country
-   *     The two letter country code to construct the locale string by the
-   *     intlDateFormatter class. Used to control the result of the
-   *     format() method if that class is available. Defaults to NULL.
-   *   - string $calendar
-   *     A calendar name to use for the date, Defaults to
-   *     DateTimePlus::CALENDAR.
-   *   - int $datetype
-   *     The datetype to use in the formatter, defaults to
-   *     IntlDateFormatter::FULL.
-   *   - int $timetype
-   *     The datetype to use in the formatter, defaults to
-   *     IntlDateFormatter::FULL.
-   *   - boolean $lenient
-   *     Whether or not to use lenient processing in the intl
-   *     formatter. Defaults to FALSE;
+   *   - format_string_type: (optional) DateTimePlus::PHP or
+   *     DateTimePlus::INTL. Identifies the pattern used by the format
+   *     string. When using the Intl formatter, the format string must
+   *     use the Intl pattern, which is different from the pattern used
+   *     by the DateTime format function. Defaults to DateTimePlus::PHP.
+   *   - timezone: (optional) String timezone name. Defaults to the timezone
+   *     of the date object.
+   *   - langcode: (optional) String two letter language code to construct the
+   *     locale string by the intlDateFormatter class. Used to control the
+   *     result of the format() method if that class is available. Defaults
+   *     to NULL.
+   *   - country: (optional) String two letter country code to construct the
+   *     locale string by the intlDateFormatter class. Used to control the
+   *     result of the format() method if that class is available. Defaults
+   *     to NULL.
+   *   - calendar: (optional) String calendar name to use for the date,
+   *     Defaults to DateTimePlus::CALENDAR.
+   *   - date_type: (optional) Integer date type to use in the formatter,
+   *     defaults to IntlDateFormatter::FULL.
+   *   - time_type: (optional) Integer date type to use in the formatter,
+   *     defaults to IntlDateFormatter::FULL.
+   *   - lenient: (optional) Boolean choice of whether or not to use lenient
+   *     processing in the intl formatter. Defaults to FALSE;
    *
    * @return string
    *   The formatted value of the date.