Add comments for utils/sticky46833-sticky-polyfill

1 files changed, 19 insertions, 0 deletions

diff --git a/app/assets/javascripts/lib/utils/sticky.js b/app/assets/javascripts/lib/utils/sticky.js
index e7dafbe70e0..d34d722b572 100644
--- a/app/assets/javascripts/lib/utils/sticky.js
+++ b/app/assets/javascripts/lib/utils/sticky.js
@@ -30,11 +30,30 @@ export const isSticky = (el, scrollY, stickyTop, insertPlaceholder) => {
   }
 };
 
+/**
+ * This function attaches listeners to support `position: sticky` behavior.
+ *
+ * Description:
+ * - For the given element, polyfill `position: sticky` in unsupported browsers.
+ * - For the given element, add a scroll listener for toggling 'is-stuck' class.
+ *
+ * @param {Element} el                                Element with `position: sticky`.
+ *
+ * @param {Number}  stickyTop                         Used to determine when `el` is stuck or not.
+ *
+ * @param {Boolean} [options.insertPlaceholder=true]  When `el` is stuck, should a placeholder
+ *                                                    element be inserted (to preserve height)?
+ *
+ * @param {Boolean} [options.hasOnStickListener=true] Should the scroll listener for toggling
+ *                                                    'is-stuck' class be created?
+ */
 export default (el, stickyTop, { insertPlaceholder = true, hasOnStickListener = true } = {}) => {
   if (!el) return;
 
+  // Add polyfill
   StickyFill.add(el);
 
+  // Add scroll listener for 'is-stuck' class
   if (hasOnStickListener) {
     document.addEventListener('scroll', () => isSticky(el, window.scrollY, stickyTop, insertPlaceholder), {
       passive: true,