diff --git a/core/lib/Drupal/Component/Gettext/PoItem.php b/core/lib/Drupal/Component/Gettext/PoItem.php
index d4d7974..599a58a 100644
--- a/core/lib/Drupal/Component/Gettext/PoItem.php
+++ b/core/lib/Drupal/Component/Gettext/PoItem.php
@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Component\Gettext\PoItem.
+ */
+
 namespace Drupal\Component\Gettext;
 
 /**
diff --git a/core/modules/locale/lib/Drupal/locale/Gettext.php b/core/modules/locale/lib/Drupal/locale/Gettext.php
index 1ff0f95..2c8833f 100644
--- a/core/modules/locale/lib/Drupal/locale/Gettext.php
+++ b/core/modules/locale/lib/Drupal/locale/Gettext.php
@@ -1,26 +1,38 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\locale\Gettext.
+ */
+
 namespace Drupal\locale;
 
 use Drupal\Component\Gettext\PoStreamReader;
 use Drupal\Component\Gettext\PoMemoryWriter;
+use Drupal\Component\Gettext\PoDatabaseWriter;
 
 /**
- * Static class providing Drupal specific functionality.
+ * Static class providing Drupal specific Gettext functionality.
  *
- * Most operations related to Gettext PO file handling are related to pumping
- * data from a source to a destination, for example:
+ * The operations are related to pumping data from a source to a destination,
+ * for example:
  * - Remote file http://*.po to memory
  * - Database to public://*.po
  */
 class Gettext {
 
   /**
-   * Reads the given PO files into a data structure.
+   * Reads the given Gettext PO files into a data structure.
    *
-   * @param type $langcode
+   * @param string $langcode
+   *   Language code string.
    * @param array $files
+   *   List of file objects with uri properties pointing to read.
+   *
    * @return array
+   *   Structured array as produced by a PoMemoryWriter.
+   *
+   * @see Drupal\Component\Gettext\PoMemoryWriter
    */
   static function filesToArray($langcode, array $files) {
     $writer = new PoMemoryWriter();
@@ -36,15 +48,26 @@ class Gettext {
   }
 
   /**
-   * Reads the given PO files into a data structure.
+   * Reads the given PO files into the database.
    *
-   * @param file $file
+   * @param stdClass $file
+   *   File object with an uri property pointing at the file's path.
    * @param string $langcode
+   *   Language code string.
    * @param array $overwrite_options
+   *   Overwrite options array as defined in Drupal\locale\PoDatabaseWriter.
    * @param boolean $customized
+   *   Flag indicating whether the string imported from $file are customized
+   *   translations or come from a community source. Use LOCALE_CUSTOMIZED or
+   *   LOCALE_NOT_CUSTOMIZED.
+   *
    * @return array
+   *   Report array as defined in Drupal\locale\PoDatabaseWriter.
+   *
+   * @see Drupal\locale\PoDatabaseWriter
    */
   static function fileToDatabase($file, $langcode, $overwrite_options, $customized = LOCALE_NOT_CUSTOMIZED) {
+    // Instantiate and initialize the stream reader for this file.
     $reader = new PoStreamReader();
     $reader->setLangcode($langcode);
     $reader->setURI($file->uri);
@@ -61,17 +84,17 @@ class Gettext {
       throw new Exception('Missing or malformed header.');
     }
 
+    // Initialize the database writer.
     $writer = new PoDatabaseWriter();
     $writer->setLangcode($langcode);
     $options = array(
       'overwrite_options' => $overwrite_options,
       'customized' => $customized,
     );
-    // It's vital options are set first.
-    // @todo: this has to be fixed in https://drupal.org/node/1637334
     $writer->setOptions($options);
     $writer->setHeader($header);
 
+    // Attempt to pipe all items from the file to the database.
     try {
       $writer->writeItems($reader, -1);
     }
@@ -79,6 +102,7 @@ class Gettext {
       throw $exception;
     }
 
+    // Report back with an array of status information.
     return $writer->getReport();
   }
 }
diff --git a/core/modules/locale/lib/Drupal/locale/PoDatabaseReader.php b/core/modules/locale/lib/Drupal/locale/PoDatabaseReader.php
index 1822cf2..c0dfc2f 100644
--- a/core/modules/locale/lib/Drupal/locale/PoDatabaseReader.php
+++ b/core/modules/locale/lib/Drupal/locale/PoDatabaseReader.php
@@ -1,49 +1,67 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\locale\PoDatabaseReader.
+ */
+
 namespace Drupal\locale;
 
 use Drupal\Component\Gettext\PoHeader;
 use Drupal\Component\Gettext\PoItem;
 use Drupal\Component\Gettext\PoReaderInterface;
 
+/**
+ * Gettext PO reader working with the locale module database.
+ */
 class PoDatabaseReader implements PoReaderInterface {
 
-  /*
-   * An associative array indicating what data should be overwritten, if any.
-   * - override_options
-   *   - not_customized: not customized strings should be overwritten.
-   *   - customized: customized strings should be overwritten.
-   * - customized: the strings being imported should be saved as customized.
-   *     Use LOCALE_CUSTOMIZED or LOCALE_NOT_CUSTOMIZED.
+  /**
+   * An associative array indicating which type of strings should be read.
+   *
+   * Elements of the array:
+   *  - not_customized: boolean indicating if not customized strings should be
+   *    read.
+   *  - customized: boolean indicating if customized strings should be read.
+   *  - no_translated: boolean indicating if non-translated should be read.
+   *
+   * The three options define three distinct sets of strings, which combined
+   * cover all strings.
+   *
+   * @var array
    */
   private $_options;
 
   /**
    * Language code of the language being read from the database.
+   *
+   * @var string
    */
   private $_langcode;
 
   /**
    * Store the result of the query so it can be iterated later.
+   *
+   * @var resource
    */
   private $_result;
 
   /**
-   * Constructor.
+   * Constructor, initializes with default options.
    */
   function __construct() {
     $this->setOptions(array());
   }
 
   /**
-   * Get the language code of the currently used language.
+   * Implements Drupal\Component\Gettext\PoMetadataInterface::getLangcode().
    */
   public function getLangcode() {
     return $this->_langcode;
   }
 
   /**
-   * Set the language code of the current language.
+   * Implements Drupal\Component\Gettext\PoMetadataInterface::setLangcode().
    */
   public function setLangcode($langcode) {
     $this->_langcode = $langcode;
@@ -60,52 +78,38 @@ class PoDatabaseReader implements PoReaderInterface {
    * Set the options for the current reader.
    */
   function setOptions(array $options) {
-    if (!isset($options['overwrite_options'])) {
-      $options['overwrite_options'] = array();
-    }
-    $options['overwrite_options'] += array(
-      'not_customized' => FALSE,
-      'customized' => FALSE,
-    );
     $options += array(
-      'customized' => LOCALE_NOT_CUSTOMIZED,
+      'customized' => FALSE,
+      'not_customized' => FALSE,
+      'not_translated' => FALSE,
     );
     $this->_options = $options;
   }
 
   /**
-   * Get the header in po format based on the current language code.
+   * Implements Drupal\Component\Gettext\PoMetadataInterface::getHeader().
    */
   function getHeader() {
     return new PoHeader($this->getLangcode());
   }
 
   /**
-   * Set the header in PO format in a reader is not allowed.
+   * Implements Drupal\Component\Gettext\PoMetadataInterface::setHeader().
    *
    * @throws Exception
-   *  Always, because you cannot set the PO header of a reader.
+   *   Always, because you cannot set the PO header of a reader.
    */
   function setHeader(PoHeader $header) {
     throw new Exception('You cannot set the PO header in a reader.');
   }
 
   /**
-   * Generates a structured array of all translated strings for the language.
-   *
-   * @return
-   *   An array of translated strings that can be used to generate an export.
+   * Builds and executes a database query based on options set earlier.
    */
   private function buildQuery() {
     $langcode = $this->_langcode;
     $options = $this->_options;
 
-    // Assume FALSE for all options if not provided by the API.
-    $options += array(
-      'customized' => FALSE,
-      'not_customized' => FALSE,
-      'not_translated' => FALSE,
-    );
     if (array_sum($options) == 0) {
       // If user asked to not include anything in the translation files,
       // that would not make sense, so just fall back on providing a template.
@@ -151,9 +155,7 @@ class PoDatabaseReader implements PoReaderInterface {
   }
 
   /**
-   * Get the full result for the given language and options.
-   *
-   * @see buildQuery
+   * Get the database result resource for the given language and options.
    */
   private function getResult() {
     if (!isset($this->_result)) {
@@ -163,9 +165,7 @@ class PoDatabaseReader implements PoReaderInterface {
   }
 
   /**
-   * Read one item at the time from the results.
-   *
-   * @see PoDatabaseWriter
+   * Implements Drupal\Component\Gettext\PoReaderInterface::readItem().
    */
   function readItem() {
     $result = $this->getResult();
diff --git a/core/modules/locale/lib/Drupal/locale/PoDatabaseWriter.php b/core/modules/locale/lib/Drupal/locale/PoDatabaseWriter.php
index e2a6ace..ba2cea1 100644
--- a/core/modules/locale/lib/Drupal/locale/PoDatabaseWriter.php
+++ b/core/modules/locale/lib/Drupal/locale/PoDatabaseWriter.php
@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\locale\PoDatabaseWriter.
+ */
+
 namespace Drupal\locale;
 
 use Drupal\Component\Gettext\PoHeader;
@@ -7,51 +12,63 @@ use Drupal\Component\Gettext\PoItem;
 use Drupal\Component\Gettext\PoReaderInterface;
 use Drupal\Component\Gettext\PoWriterInterface;
 
-
+/**
+ * Gettext PO writer working with the locale module database.
+ */
 class PoDatabaseWriter implements PoWriterInterface {
 
-  /*
+  /**
    * An associative array indicating what data should be overwritten, if any.
+   *
+   * Elements of the array:
    * - override_options
-   *   - not_customized: not customized strings should be overwritten.
-   *   - customized: customized strings should be overwritten.
+   *   - not_customized: boolean indicating that not customized strings should
+   *     be overwritten.
+   *   - customized: boolean indicating that customized strings should be
+   *     overwritten.
    * - customized: the strings being imported should be saved as customized.
-   *     Use LOCALE_CUSTOMIZED or LOCALE_NOT_CUSTOMIZED.
+   *     One of LOCALE_CUSTOMIZED or LOCALE_NOT_CUSTOMIZED.
+   *
+   * @var array
    */
   private $_options;
 
   /**
    * Language code of the language being written to the database.
+   *
+   * @var string
    */
   private $_langcode;
 
   /**
    * Header of the po file written to the database.
+   *
+   * @var Drupal\Component\Gettext\PoHeader
    */
   private $_header;
 
   /**
-   * Report array summarizing the number of changes done in the form:
-   * array(additions, updates, deletes, skips, ignored).
+   * Associative array summarizing the number of changes done.
+   *
+   * Keys for the array:
+   *  - additions: number of source strings newly added
+   *  - updates: number of translations updated
+   *  - deletes: number of translations deleted
+   *  - skips: number of strings skipped due to disallowed HTML
+   *
+   * @var array
    */
   private $_report;
 
   /**
-   * Constructor.
-   */
-  function __construct() {
-    $this->setState(array());
-  }
-
-  /**
-   * Get the language code of the currently used language.
+   * Implements Drupal\Component\Gettext\PoMetadataInterface::getLangcode().
    */
   public function getLangcode() {
     return $this->_langcode;
   }
 
   /**
-   * Set the language code of the current language.
+   * Implements Drupal\Component\Gettext\PoMetadataInterface::setLangcode().
    */
   public function setLangcode($langcode) {
     $this->_langcode = $langcode;
@@ -73,7 +90,6 @@ class PoDatabaseWriter implements PoWriterInterface {
       'updates' => 0,
       'deletes' => 0,
       'skips' => 0,
-      'ignored' => 0,
     );
     $this->_report = $report;
   }
@@ -103,23 +119,25 @@ class PoDatabaseWriter implements PoWriterInterface {
   }
 
   /**
-   * Get the header.
-   * @return PoHeader
-   * @see setHeader
+   * Implements Drupal\Component\Gettext\PoMetadataInterface::getHeader().
    */
   function getHeader() {
     return $this->_header;
   }
 
   /**
+   * Implements Drupal\Component\Gettext\PoMetadataInterface::setHeader().
+   *
    * Sets the header and configure Drupal accordingly.
    *
    * Before being able to process the given header we need to know in what
    * context this database write is done. For this the options must be set.
    *
-   * A langcode is required to set the current headers PluralForm.
+   * A langcode is required to set the current header's PluralForm.
+   *
+   * @param Drupal\Component\Gettext\PoHeader $header
+   *   Header metadata.
    *
-   * @param PoHeader $header
    * @throws Exception
    */
   function setHeader(PoHeader $header) {
@@ -129,17 +147,17 @@ class PoDatabaseWriter implements PoWriterInterface {
     // Check for options.
     $options = $this->getOptions();
     if (empty($options)) {
-      throw new Exception("Options should be set before assigning a PoHeader");
+      throw new Exception("Options should be set before assigning a PoHeader.");
     }
     $overwrite_options = $options['overwrite_options'];
 
     // Check for langcode.
-    $lang = $this->_langcode;
-    if (empty($lang)) {
-      throw new Exception("Langcode should be set before assigning a PoHeader");
+    $langcode = $this->_langcode;
+    if (empty($langcode)) {
+      throw new Exception("Langcode should be set before assigning a PoHeader.");
     }
 
-    if (array_sum($overwrite_options) || empty($locale_plurals[$lang]['plurals'])) {
+    if (array_sum($overwrite_options) || empty($locale_plurals[$langcode]['plurals'])) {
       // Get and store the plural formula if available.
       $plural = $header->getPluralForms();
       if (isset($plural) && $p = $header->parsePluralForms($plural)) {
@@ -154,25 +172,18 @@ class PoDatabaseWriter implements PoWriterInterface {
   }
 
   /**
-   * Write a PoItem to the database.
-   *
-   * @param PoItem $item
+   * Implements Drupal\Component\Gettext\PoWriterInterface::writeItem().
    */
   function writeItem(PoItem $item) {
     if ($item->isPlural()) {
       $item->setSource(join(LOCALE_PLURAL_DELIMITER, $item->getSource()));
       $item->setTranslation(join(LOCALE_PLURAL_DELIMITER, $item->getTranslation()));
     }
-    $this->importString($item, 'location');
+    $this->importString($item);
   }
 
   /**
-   * Write one or more PoItems to the database.
-   *
-   * @param PoReaderInterface $reader
-   *   Reader to read PoItem's from
-   * @param $count
-   *   When $count == -1 all items are read from the $reader.
+   * Implements Drupal\Component\Gettext\PoWriterInterface::writeItems().
    */
   public function writeItems(PoReaderInterface $reader, $count = -1) {
     $forever = $count == -1;
@@ -184,15 +195,13 @@ class PoDatabaseWriter implements PoWriterInterface {
   /**
    * Imports one string into the database.
    *
-   * @param PoItem $item
-   *  The item being imported.
-   * @param $location
-   *   Location value to save with source string.
+   * @param Drupal\Component\Gettext\PoItem $item
+   *   The item being imported.
    *
-   * @return
+   * @return int
    *   The string ID of the existing string modified or the new string added.
    */
-  private function importString($item, $location) {
+  private function importString(PoItem $item) {
     // Initialize overwrite options if not set.
     $this->_options['overwrite_options'] += array(
       'not_customized' => FALSE,
@@ -222,37 +231,29 @@ class PoDatabaseWriter implements PoWriterInterface {
         return 0;
       }
       elseif (isset($string->lid)) {
-        // We have this source string saved already.
-        db_update('locales_source')
-            ->fields(array(
-              'location' => $location,
-            ))
-            ->condition('lid', $string->lid)
-            ->execute();
-
         if (!isset($string->customized)) {
           // No translation in this language.
           db_insert('locales_target')
-              ->fields(array(
-                'lid' => $string->lid,
-                'language' => $this->_langcode,
-                'translation' => $translation,
-                'customized' => $customized,
-              ))
-              ->execute();
+            ->fields(array(
+              'lid' => $string->lid,
+              'language' => $this->_langcode,
+              'translation' => $translation,
+              'customized' => $customized,
+            ))
+            ->execute();
 
           $this->_report['additions']++;
         }
         elseif ($overwrite_options[$string->customized ? 'customized' : 'not_customized']) {
           // Translation exists, only overwrite if instructed.
           db_update('locales_target')
-              ->fields(array(
-                'translation' => $translation,
-                'customized' => $customized,
-              ))
-              ->condition('language', $this->_langcode)
-              ->condition('lid', $string->lid)
-              ->execute();
+            ->fields(array(
+              'translation' => $translation,
+              'customized' => $customized,
+            ))
+            ->condition('language', $this->_langcode)
+            ->condition('lid', $string->lid)
+            ->execute();
 
           $this->_report['updates']++;
         }
@@ -261,21 +262,20 @@ class PoDatabaseWriter implements PoWriterInterface {
       else {
         // No such source string in the database yet.
         $lid = db_insert('locales_source')
-            ->fields(array(
-              'location' => $location,
-              'source' => $source,
-              'context' => $context,
-            ))
-            ->execute();
+          ->fields(array(
+            'source' => $source,
+            'context' => $context,
+          ))
+          ->execute();
 
         db_insert('locales_target')
-            ->fields(array(
-              'lid' => $lid,
-              'language' => $this->_langcode,
-              'translation' => $translation,
-              'customized' => $customized,
-            ))
-            ->execute();
+          ->fields(array(
+            'lid' => $lid,
+            'language' => $this->_langcode,
+            'translation' => $translation,
+            'customized' => $customized,
+          ))
+          ->execute();
 
         $this->_report['additions']++;
         return $lid;
@@ -284,61 +284,13 @@ class PoDatabaseWriter implements PoWriterInterface {
     elseif (isset($string->lid) && isset($string->customized) && $overwrite_options[$string->customized ? 'customized' : 'not_customized']) {
       // Empty translation, remove existing if instructed.
       db_delete('locales_target')
-          ->condition('language', $this->_langcode)
-          ->condition('lid', $string->lid)
-          ->execute();
+        ->condition('language', $this->_langcode)
+        ->condition('lid', $string->lid)
+        ->execute();
 
       $this->_report['deletes']++;
       return $string->lid;
     }
   }
 
-  /**
-   * Default state for the database writer.
-   */
-  static function getDefaultState() {
-    return array(
-      'langcode' => NULL,
-      'report' => array(
-        'additions' => 0,
-        'updates' => 0,
-        'deletes' => 0,
-        'skips' => 0,
-        'ignored' => 0,
-      ),
-      'options' => array(
-        'overwrite_options' => array(
-          'not_customized' => FALSE,
-          'customized' => FALSE,
-        ),
-        'customized' => LOCALE_NOT_CUSTOMIZED,
-      ),
-    );
-  }
-
-  /**
-   * Set the state for in between file batch API.
-   *
-   * @param array $state
-   */
-  public function setState(array $state) {
-    $state += self::getDefaultState();
-    $this->_report = $state['report'];
-    $this->setLangcode($state['langcode']);
-    $this->setOptions($state['options']);
-  }
-
-  /**
-   * Get the state for in between file batch API.
-   *
-   * @return array $state
-   */
-  public function getState() {
-    return array(
-      'class' => __CLASS__,
-      'report' => $this->getReport(),
-      'langcode' => $this->getLangcode(),
-      'options' => $this->getOptions(),
-    );
-  }
 }