Precise usage & better comments

assets/scripts/modules/Scroll.js

@@ -24,11 +24,21 @@ export default class extends module {
     }
 
     /**
-     * Lazy load
+     * Lazy load the related image.
-     * See '../utils/image'
-     * Recommended to wrap your image in `.c-lazy`. `-lazy-loaded` modifier will be applied on both parent and children
      *
-     * @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, () => {

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 {HTMLImageElement} $el      - The image element.
- * @param {string} | url
+ * @param {?string}          url      - The URI to lazy load into $el.
- * @param {function} | callback
+ *     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)