diff --git a/docs/how-to-create-new-effects.md b/docs/how-to-create-new-effects.md
index 730c131..a69d5ae 100644
--- a/docs/how-to-create-new-effects.md
+++ b/docs/how-to-create-new-effects.md
@@ -150,13 +150,15 @@ var SimpleFade = class SimpleFade {
     return new Shader(settings);
   }
 
-  // This is also called from extension.js. It is used to tweak a window's open / close
+  // The tweakTransition() is called from extension.js to tweak a window's open / close
   // transitions - usually windows are faded in / out and scaled up / down by GNOME Shell.
   // The parameter 'forOpening' is set to true if this is called for a window-open
   // transition, for a window-close transition it is set to false. The modes can be set to
   // any value from here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode.
-  // This also determines how the uProgress uniform value will progress in the shader.
+  // The only required property is 'opacity', even if it transitions from 1.0 to 1.0. The
+  // current value of the opacity transition is passed as uProgress to the shader.
   // Tweaking the actor's scale during the transition only works properly for GNOME 3.38+.
+
   // For this effect, windows should neither be scaled nor faded.
   static tweakTransition(actor, settings, forOpening) {
     return {
diff --git a/src/BrokenGlass.js b/src/BrokenGlass.js
index 3646693..26c5cc4 100644
--- a/src/BrokenGlass.js
+++ b/src/BrokenGlass.js
@@ -83,12 +83,15 @@ var BrokenGlass = class BrokenGlass {
     return new Shader(actor, settings, forOpening);
   }
 
-  // This is also called from extension.js. It is used to tweak a window's open / close
+  // The tweakTransition() is called from extension.js to tweak a window's open / close
   // transitions - usually windows are faded in / out and scaled up / down by GNOME Shell.
-  // forOpening is set to true if this is called for a window-open transition, for a
-  // window-close transition it is set to false. The modes can be set to any value from
-  // here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode. This also
-  // determines how the uProgress uniform value will progress in the shader.
+  // The parameter 'forOpening' is set to true if this is called for a window-open
+  // transition, for a window-close transition it is set to false. The modes can be set to
+  // any value from here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode.
+  // The only required property is 'opacity', even if it transitions from 1.0 to 1.0. The
+  // current value of the opacity transition is passed as uProgress to the shader.
+  // Tweaking the actor's scale during the transition only works properly for GNOME 3.38+.
+
   // For this effect, windows are set to twice their original size, so that
   // we have some space to draw the shards. We also set the animation mode to "Linear".
   static tweakTransition(actor, settings, forOpening) {
diff --git a/src/EnergizeA.js b/src/EnergizeA.js
index a7ef50d..5cbef47 100644
--- a/src/EnergizeA.js
+++ b/src/EnergizeA.js
@@ -78,12 +78,15 @@ var EnergizeA = class EnergizeA {
     return new Shader(settings, forOpening);
   }
 
-  // This is also called from extension.js. It is used to tweak a window's open / close
+  // The tweakTransition() is called from extension.js to tweak a window's open / close
   // transitions - usually windows are faded in / out and scaled up / down by GNOME Shell.
-  // forOpening is set to true if this is called for a window-open transition, for a
-  // window-close transition it is set to false. The modes can be set to any value from
-  // here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode. This also
-  // determines how the uProgress uniform value will progress in the shader.
+  // The parameter 'forOpening' is set to true if this is called for a window-open
+  // transition, for a window-close transition it is set to false. The modes can be set to
+  // any value from here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode.
+  // The only required property is 'opacity', even if it transitions from 1.0 to 1.0. The
+  // current value of the opacity transition is passed as uProgress to the shader.
+  // Tweaking the actor's scale during the transition only works properly for GNOME 3.38+.
+
   // For this effect, windows should neither be scaled nor faded.
   static tweakTransition(actor, settings, forOpening) {
     return {
diff --git a/src/EnergizeB.js b/src/EnergizeB.js
index fe3973e..37dd1a1 100644
--- a/src/EnergizeB.js
+++ b/src/EnergizeB.js
@@ -78,12 +78,15 @@ var EnergizeB = class EnergizeB {
     return new Shader(settings, forOpening);
   }
 
-  // This is also called from extension.js. It is used to tweak a window's open / close
+  // The tweakTransition() is called from extension.js to tweak a window's open / close
   // transitions - usually windows are faded in / out and scaled up / down by GNOME Shell.
-  // forOpening is set to true if this is called for a window-open transition, for a
-  // window-close transition it is set to false. The modes can be set to any value from
-  // here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode. This also
-  // determines how the uProgress uniform value will progress in the shader.
+  // The parameter 'forOpening' is set to true if this is called for a window-open
+  // transition, for a window-close transition it is set to false. The modes can be set to
+  // any value from here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode.
+  // The only required property is 'opacity', even if it transitions from 1.0 to 1.0. The
+  // current value of the opacity transition is passed as uProgress to the shader.
+  // Tweaking the actor's scale during the transition only works properly for GNOME 3.38+.
+
   // For this effect, windows should neither be scaled nor faded.
   static tweakTransition(actor, settings, forOpening) {
     return {
diff --git a/src/Fire.js b/src/Fire.js
index eecbeb0..b824c74 100644
--- a/src/Fire.js
+++ b/src/Fire.js
@@ -100,12 +100,15 @@ var Fire = class Fire {
     return new Shader(settings, forOpening);
   }
 
-  // This is also called from extension.js. It is used to tweak a window's open / close
+  // The tweakTransition() is called from extension.js to tweak a window's open / close
   // transitions - usually windows are faded in / out and scaled up / down by GNOME Shell.
-  // forOpening is set to true if this is called for a window-open transition, for a
-  // window-close transition it is set to false. The modes can be set to any value from
-  // here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode. This also
-  // determines how the uProgress uniform value will progress in the shader.
+  // The parameter 'forOpening' is set to true if this is called for a window-open
+  // transition, for a window-close transition it is set to false. The modes can be set to
+  // any value from here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode.
+  // The only required property is 'opacity', even if it transitions from 1.0 to 1.0. The
+  // current value of the opacity transition is passed as uProgress to the shader.
+  // Tweaking the actor's scale during the transition only works properly for GNOME 3.38+.
+
   // For this effect, windows should neither be scaled nor faded.
   static tweakTransition(actor, settings, forOpening) {
     return {
diff --git a/src/Matrix.js b/src/Matrix.js
index 329ea42..bed7983 100644
--- a/src/Matrix.js
+++ b/src/Matrix.js
@@ -85,12 +85,15 @@ var Matrix = class Matrix {
     return new Shader(settings, forOpening);
   }
 
-  // This is also called from extension.js. It is used to tweak a window's open / close
+  // The tweakTransition() is called from extension.js to tweak a window's open / close
   // transitions - usually windows are faded in / out and scaled up / down by GNOME Shell.
-  // forOpening is set to true if this is called for a window-open transition, for a
-  // window-close transition it is set to false. The modes can be set to any value from
-  // here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode. This also
-  // determines how the uProgress uniform value will progress in the shader.
+  // The parameter 'forOpening' is set to true if this is called for a window-open
+  // transition, for a window-close transition it is set to false. The modes can be set to
+  // any value from here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode.
+  // The only required property is 'opacity', even if it transitions from 1.0 to 1.0. The
+  // current value of the opacity transition is passed as uProgress to the shader.
+  // Tweaking the actor's scale during the transition only works properly for GNOME 3.38+.
+
   // For this effect, windows should not be faded but scaled vertically to allow for some
   // overshooting.
   static tweakTransition(actor, settings, forOpening) {
diff --git a/src/TRexAttack.js b/src/TRexAttack.js
index e161100..123c9dc 100644
--- a/src/TRexAttack.js
+++ b/src/TRexAttack.js
@@ -82,12 +82,15 @@ var TRexAttack = class TRexAttack {
     return new Shader(settings, forOpening);
   }
 
-  // This is also called from extension.js. It is used to tweak a window's open / close
+  // The tweakTransition() is called from extension.js to tweak a window's open / close
   // transitions - usually windows are faded in / out and scaled up / down by GNOME Shell.
-  // forOpening is set to true if this is called for a window-open transition, for a
-  // window-close transition it is set to false. The modes can be set to any value from
-  // here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode. This also
-  // determines how the uProgress uniform value will progress in the shader.
+  // The parameter 'forOpening' is set to true if this is called for a window-open
+  // transition, for a window-close transition it is set to false. The modes can be set to
+  // any value from here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode.
+  // The only required property is 'opacity', even if it transitions from 1.0 to 1.0. The
+  // current value of the opacity transition is passed as uProgress to the shader.
+  // Tweaking the actor's scale during the transition only works properly for GNOME 3.38+.
+
   // For this effect, we slightly increase the window's scale as part of the warp effect.
   static tweakTransition(actor, settings, forOpening) {
     const warp = 1.0 + 0.5 * settings.get_double('claw-scratch-warp');
diff --git a/src/TVEffect.js b/src/TVEffect.js
index e022f55..80be7bc 100644
--- a/src/TVEffect.js
+++ b/src/TVEffect.js
@@ -79,12 +79,15 @@ var TVEffect = class TVEffect {
     return new Shader(settings, forOpening);
   }
 
-  // This is also called from extension.js. It is used to tweak a window's open / close
+  // The tweakTransition() is called from extension.js to tweak a window's open / close
   // transitions - usually windows are faded in / out and scaled up / down by GNOME Shell.
-  // forOpening is set to true if this is called for a window-open transition, for a
-  // window-close transition it is set to false. The modes can be set to any value from
-  // here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode. This also
-  // determines how the uProgress uniform value will progress in the shader.
+  // The parameter 'forOpening' is set to true if this is called for a window-open
+  // transition, for a window-close transition it is set to false. The modes can be set to
+  // any value from here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode.
+  // The only required property is 'opacity', even if it transitions from 1.0 to 1.0. The
+  // current value of the opacity transition is passed as uProgress to the shader.
+  // Tweaking the actor's scale during the transition only works properly for GNOME 3.38+.
+
   // For this effect, windows are scaled down vertically.
   static tweakTransition(actor, settings, forOpening) {
     return {
diff --git a/src/Wisps.js b/src/Wisps.js
index 4722af9..5d5f6b7 100644
--- a/src/Wisps.js
+++ b/src/Wisps.js
@@ -79,12 +79,15 @@ var Wisps = class Wisps {
     return new Shader(settings, forOpening);
   }
 
-  // This is also called from extension.js. It is used to tweak a window's open / close
+  // The tweakTransition() is called from extension.js to tweak a window's open / close
   // transitions - usually windows are faded in / out and scaled up / down by GNOME Shell.
-  // forOpening is set to true if this is called for a window-open transition, for a
-  // window-close transition it is set to false. The modes can be set to any value from
-  // here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode. This also
-  // determines how the uProgress uniform value will progress in the shader.
+  // The parameter 'forOpening' is set to true if this is called for a window-open
+  // transition, for a window-close transition it is set to false. The modes can be set to
+  // any value from here: https://gjs-docs.gnome.org/clutter8~8_api/clutter.animationmode.
+  // The only required property is 'opacity', even if it transitions from 1.0 to 1.0. The
+  // current value of the opacity transition is passed as uProgress to the shader.
+  // Tweaking the actor's scale during the transition only works properly for GNOME 3.38+.
+
   // For this effect, windows should be scaled down slightly but not faded.
   static tweakTransition(actor, settings, forOpening) {
     return {