diff --git a/core/lib/Drupal/Core/File/MimeType/ExtensionMimeTypeGuesser.php b/core/lib/Drupal/Core/File/MimeType/ExtensionMimeTypeGuesser.php
index 9119048..74c2916 100644
--- a/core/lib/Drupal/Core/File/MimeType/ExtensionMimeTypeGuesser.php
+++ b/core/lib/Drupal/Core/File/MimeType/ExtensionMimeTypeGuesser.php
@@ -17,14 +17,14 @@ class ExtensionMimeTypeGuesser implements MimeTypeGuesserInterface {
   /**
    * The MIME type mapper to use for guessing.
    *
-   * @var MimeTypeMapperInterface
+   * @var \Drupal\Core\File\MimeType\MimeTypeMapperInterface
    */
   protected $mapper;
 
   /**
    * Constructs a new ExtensionMimeTypeGuesser.
    *
-   * @param MimeTypeMapperInterface $mapper
+   * @param \Drupal\Core\File\MimeType\MimeTypeMapperInterface $mapper
    *   A MIME type mapper.
    */
   public function __construct(MimeTypeMapperInterface $mapper) {
diff --git a/core/lib/Drupal/Core/File/MimeType/MimeTypeMapper.php b/core/lib/Drupal/Core/File/MimeType/MimeTypeMapper.php
index f7c37a3..bdb34e5 100644
--- a/core/lib/Drupal/Core/File/MimeType/MimeTypeMapper.php
+++ b/core/lib/Drupal/Core/File/MimeType/MimeTypeMapper.php
@@ -887,7 +887,19 @@ public function __construct(ModuleHandlerInterface $module_handler) {
   }
 
   /**
-   * {@inheritdoc}
+   * Returns the mapping from file extensions to appropriate MIME types.
+   *
+   * Invokes hook_file_mimetype_mapping_alter() to allow modules to alter
+   * the mapping.
+   *
+   * @return array
+   *   An array consisting of two arrays:
+   *     - mimetypes: MIME types, keyed by a unique number.
+   *     - extensions: an associative array with the MIME type key numbers as
+   *       values. The keys are file extensions, in lower case and without any
+   *       preceding dot.
+   *
+   * @see hook_file_mimetype_mapping_alter()
    */
   protected function getMapping() {
     if (!$this->isMappingAltered) {
@@ -902,7 +914,10 @@ protected function getMapping() {
    * {@inheritdoc}
    */
   public function addMapping($mimetype, $extension) {
+    // Calls ::getMapping() to make sure new mappings are added to the
+    // ::$mapping array that has been altered by modules already.
     $this->getMapping();
+
     if (!in_array($mimetype, $this->mapping['mimetypes'])) {
       $this->mapping['mimetypes'][] = $mimetype;
     }
diff --git a/core/modules/system/file.api.php b/core/modules/system/file.api.php
index 135a1de..ea13843 100644
--- a/core/modules/system/file.api.php
+++ b/core/modules/system/file.api.php
@@ -104,11 +104,12 @@ function hook_file_url_alter(&$uri) {
  *
  * Invoked by \Drupal\Core\File\MimeType\MimeTypeMapper::getMapping(). It
  * is used to allow modules to add to or modify the default mapping from
- * \Drupal\Core\File\MimeType\MimeTypeMapper::$mapping. Implementations
- * should use the \Drupal\Core\File\MimeType\MimeTypeMapper::addMapping()
+ * \Drupal\Core\File\MimeType\MimeTypeMapper::$mapping. Implementations should
+ * use the \Drupal\Core\File\MimeType\MimeTypeMapperInterface::addMapping()
  * method to add/override MIME type to extension mapping. The
- * \Drupal\Core\File\MimeType\MimeTypeMapper::getMimeTypeForExtension() and
- * \Drupal\Core\File\MimeType\MimeTypeMapper::getExtensionsForMimeType()
+ * \Drupal\Core\File\MimeType\MimeTypeMapperInterface::getMimeTypeForExtension()
+ * and
+ * \Drupal\Core\File\MimeType\MimeTypeMapperInterface::getExtensionsForMimeType()
  * methods can be used to get the current mapping respectively of the MIME
  * type of a given extension, and of the extensions associated to a given
  * MIME type.
@@ -116,9 +117,9 @@ function hook_file_url_alter(&$uri) {
  * @param \Drupal\Core\File\MimeType\MimeTypeMapperInterface $mime_type_mapper
  *   The MIME type mapper object.
  *
- * @see \Drupal\Core\File\MimeType\MimeTypeMapper::addMapping()
- * @see \Drupal\Core\File\MimeType\MimeTypeMapper::getMimeTypeForExtension()
- * @see \Drupal\Core\File\MimeType\MimeTypeMapper::getExtensionsForMimeType()
+ * @see \Drupal\Core\File\MimeType\MimeTypeMapperInterface::addMapping()
+ * @see \Drupal\Core\File\MimeType\MimeTypeMapperInterface::getMimeTypeForExtension()
+ * @see \Drupal\Core\File\MimeType\MimeTypeMapperInterface::getExtensionsForMimeType()
  */
 function hook_file_mimetype_mapping_alter(\Drupal\Core\File\MimeType\MimeTypeMapperInterface $mime_type_mapper) {
   // Add new MIME type 'drupal/info', and map it to a new extension
diff --git a/core/modules/system/src/Tests/File/MimeTypeTest.php b/core/modules/system/src/Tests/File/MimeTypeTest.php
index 453e02f..1fec540 100644
--- a/core/modules/system/src/Tests/File/MimeTypeTest.php
+++ b/core/modules/system/src/Tests/File/MimeTypeTest.php
@@ -92,8 +92,9 @@ public function testFileMimeTypeDetection() {
       $this->assertIdentical($output, $expected, String::format('Mimetype (using altered mappings) for %input is %output (expected: %expected).', array('%input' => $input, '%output' => $output, '%expected' => $expected)));
     }
 
-    // Now test the extensions returned by the MIME type mapper given
-    // a MIME type.
+    // Now test that MIME types added via alter hook or directly via
+    // MimeTypeMapper::addMapping are present in the list returned by
+    // MimeTypeMapper::getMimeTypes.
     $test_case = [
       'bar/foo' => ['jar'],
       'fox/trot' => ['jpg'],
@@ -103,10 +104,14 @@ public function testFileMimeTypeDetection() {
       'madeup/doc' => ['doc'],
       'drupal/info' => ['info.yml'],
     ];
+    $expected = array_keys($test_case);
+    $this->assertIdentical(array_intersect($expected, $mime_type_mapper->getMimeTypes()), $expected, 'Mime type mappings added via alter hook and directly are present.');
+
+    // Now test the extensions returned by the MIME type mapper given
+    // a MIME type.
     foreach ($test_case as $input => $expected) {
       $extensions = $mime_type_mapper->getExtensionsForMimeType($input);
       $this->assertIdentical($extensions, $expected, String::format('File extensions (using altered mappings) for %input are \'%output\' (expected: \'%expected\').', array('%input' => $input, '%output' => implode(', ', $extensions), '%expected' => implode(', ', $expected))));
     }
   }
-
 }