From 7d35dcbf28ef15a3e5b6c65f7385d106261f64b3 Mon Sep 17 00:00:00 2001
From: Deven Caron <devencaron@gmail.com>
Date: Tue, 19 Oct 2021 14:41:43 -0400
Subject: [PATCH] Precise usage & better comments

---
 assets/scripts/modules/Scroll.js | 18 ++++++++++++++----
 assets/scripts/utils/image.js    | 11 ++++++-----
 2 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/assets/scripts/modules/Scroll.js b/assets/scripts/modules/Scroll.js
index 3ac98567..82f1382c 100644
--- a/assets/scripts/modules/Scroll.js
+++ b/assets/scripts/modules/Scroll.js
@@ -24,11 +24,21 @@ export default class extends module {
     }
 
     /**
-     * Lazy load
-     * See '../utils/image'
-     * Recommended to wrap your image in `.c-lazy`. `-lazy-loaded` modifier will be applied on both parent and children
+     * Lazy load the related image.
      *
-     * @param {obj} | Locomotive Scroll object
+     * @see ../utils/image.js
+     *
+     * It is recommended to wrap your `<img>` into an element with the
+     * CSS class name `.c-lazy`. The CSS class name modifier `.-lazy-loaded`
+     * will be applied on both the image and the parent wrapper.
+     *
+     * ```html
+     * <div class="c-lazy o-ratio u-4:3">
+     *     <img data-scroll data-scroll-call="lazyLoad, Scroll, main" data-src="http://picsum.photos/640/480?v=1" alt="" src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==" />
+     * </div>
+     * ```
+     *
+     * @param {LocomotiveScroll} args - The Locomotive Scroll instance.
      */
     lazyLoad(args) {
         lazyLoadImage(args.obj.target, null, () => {
diff --git a/assets/scripts/utils/image.js b/assets/scripts/utils/image.js
index 90f01b70..31506c97 100644
--- a/assets/scripts/utils/image.js
+++ b/assets/scripts/utils/image.js
@@ -39,13 +39,14 @@ export function getImageMetadata($img) {
 }
 
 /**
- * Lazy load images
+ * Lazy load the given image.
  *
- * @param {node} | $el
- * @param {string} | url
- * @param {function} | callback
+ * @param {HTMLImageElement} $el      - The image element.
+ * @param {?string}          url      - The URI to lazy load into $el.
+ *     If falsey, the value of the `data-src` attribute on $el will be used as the URI.
+ * @param {?function}        callback - A function to call when the image is loaded.
  */
-export async function lazyLoadImage($el, url, callback = () => {}) {
+export async function lazyLoadImage($el, url, callback) {
     let src = url ? url : $el.dataset.src
 
     let loadedImage = LAZY_LOADED_IMAGES.find(image => image.url === src)