core/modules/image/src/ImageEffectBase.php                       | 4 +++-
 core/modules/image/src/ImageEffectInterface.php                  | 9 ++++++---
 core/modules/image/src/Plugin/ImageEffect/ConvertImageEffect.php | 6 ------
 .../image/src/Plugin/ImageEffect/DesaturateImageEffect.php       | 6 ------
 core/modules/image/src/Tests/ImageDimensionsTest.php             | 3 +--
 .../src/Plugin/ImageEffect/NullTestImageEffect.php               | 8 ++++++++
 6 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/core/modules/image/src/ImageEffectBase.php b/core/modules/image/src/ImageEffectBase.php
index 3b3bbb7..d0ef256 100644
--- a/core/modules/image/src/ImageEffectBase.php
+++ b/core/modules/image/src/ImageEffectBase.php
@@ -71,7 +71,9 @@ public static function create(ContainerInterface $container, array $configuratio
    * {@inheritdoc}
    */
   public function transformDimensions(array &$dimensions) {
-    $dimensions['width'] = $dimensions['height'] = NULL;
+    // Most image effects will not change the dimensions. This base
+    // implementation represents this behavior. Override this method if your
+    // image effect does change the dimensions.
   }
 
   /**
diff --git a/core/modules/image/src/ImageEffectInterface.php b/core/modules/image/src/ImageEffectInterface.php
index 790d7b2..7d2c4ca 100644
--- a/core/modules/image/src/ImageEffectInterface.php
+++ b/core/modules/image/src/ImageEffectInterface.php
@@ -37,9 +37,12 @@ public function applyEffect(ImageInterface $image);
   /**
    * Determines the dimensions of the styled image.
    *
-   * @param array $dimensions
-   *   Dimensions to be modified - an array with components width and height, in
-   *   pixels.
+   * @param array &$dimensions
+   *   Dimensions to be modified - an array with the following keys:
+   *   - width: the width in pixels, or NULL if unknown
+   *   - height: the height in pixels, or NULL if unknown
+   *   When either of the dimensions are NULL, the corresponding HTML attribute
+   *   will be omitted when an image style using this image effect is used.
    */
   public function transformDimensions(array &$dimensions);
 
diff --git a/core/modules/image/src/Plugin/ImageEffect/ConvertImageEffect.php b/core/modules/image/src/Plugin/ImageEffect/ConvertImageEffect.php
index d88712c..8d78514 100644
--- a/core/modules/image/src/Plugin/ImageEffect/ConvertImageEffect.php
+++ b/core/modules/image/src/Plugin/ImageEffect/ConvertImageEffect.php
@@ -26,12 +26,6 @@ class ConvertImageEffect extends ConfigurableImageEffectBase {
   /**
    * {@inheritdoc}
    */
-  public function transformDimensions(array &$dimensions) {
-  }
-
-  /**
-   * {@inheritdoc}
-   */
   public function applyEffect(ImageInterface $image) {
     if (!$image->convert($this->configuration['extension'])) {
       $this->logger->error('Image convert failed using the %toolkit toolkit on %path (%mimetype)', array('%toolkit' => $image->getToolkitId(), '%path' => $image->getSource(), '%mimetype' => $image->getMimeType()));
diff --git a/core/modules/image/src/Plugin/ImageEffect/DesaturateImageEffect.php b/core/modules/image/src/Plugin/ImageEffect/DesaturateImageEffect.php
index 97d31d8..008f6a8 100644
--- a/core/modules/image/src/Plugin/ImageEffect/DesaturateImageEffect.php
+++ b/core/modules/image/src/Plugin/ImageEffect/DesaturateImageEffect.php
@@ -24,12 +24,6 @@ class DesaturateImageEffect extends ImageEffectBase {
   /**
    * {@inheritdoc}
    */
-  public function transformDimensions(array &$dimensions) {
-  }
-
-  /**
-   * {@inheritdoc}
-   */
   public function applyEffect(ImageInterface $image) {
     if (!$image->desaturate()) {
       $this->logger->error('Image desaturate failed using the %toolkit toolkit on %path (%mimetype, %dimensions)', array('%toolkit' => $image->getToolkitId(), '%path' => $image->getSource(), '%mimetype' => $image->getMimeType(), '%dimensions' => $image->getWidth() . 'x' . $image->getHeight()));
diff --git a/core/modules/image/src/Tests/ImageDimensionsTest.php b/core/modules/image/src/Tests/ImageDimensionsTest.php
index 4d6c76b..2db7e24 100644
--- a/core/modules/image/src/Tests/ImageDimensionsTest.php
+++ b/core/modules/image/src/Tests/ImageDimensionsTest.php
@@ -221,8 +221,7 @@ function testImageDimensions() {
     $effect_plugin = $style->getEffect($effect_id);
     $style->deleteImageEffect($effect_plugin);
 
-    // Ensure that an effect with no dimensions callback unsets the dimensions.
-    // This ensures compatibility with 7.0 contrib modules.
+    // Ensure that an effect can unset dimensions.
     $effect = array(
       'id' => 'image_module_test_null',
       'data' => array(),
diff --git a/core/modules/image/tests/modules/image_module_test/src/Plugin/ImageEffect/NullTestImageEffect.php b/core/modules/image/tests/modules/image_module_test/src/Plugin/ImageEffect/NullTestImageEffect.php
index 8fd8632..bcf63ef 100644
--- a/core/modules/image/tests/modules/image_module_test/src/Plugin/ImageEffect/NullTestImageEffect.php
+++ b/core/modules/image/tests/modules/image_module_test/src/Plugin/ImageEffect/NullTestImageEffect.php
@@ -23,6 +23,14 @@ class NullTestImageEffect extends ImageEffectBase {
   /**
    * {@inheritdoc}
    */
+  public function transformDimensions(array &$dimensions) {
+    // Unset image dimensions.
+    $dimensions['width'] = $dimensions['height'] = NULL;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
   public function applyEffect(ImageInterface $image) {
     return TRUE;
   }