Add documentation for polyfills

When looking into our polyfills, having to look up _why_ we polyfill was
a bit tedious, so let's add documentation on the why!

This will make it way easier to remove outdated polyfills once we
deprecate a browser.

app/assets/javascripts/commons/polyfills.js

@@ -8,7 +8,17 @@
  * @see https://caniuse.com/#feat=fetch
  */
 import 'unfetch/polyfill/index';
+
+/**
+ * Polyfill: FormData APIs
+ * @what delete(), get(), getAll(), has(), set(), entries(), keys(), values(),
+ *    and support for for...of
+ * @why Because Apollo GraphQL client relies on fetch
+ * @browsers Internet Explorer 11, Edge < 18
+ * @see https://caniuse.com/#feat=mdn-api_formdata and subfeatures
+ */
 import 'formdata-polyfill';
+
 import './polyfills/custom_event';
 import './polyfills/element';
 import './polyfills/event';

app/assets/javascripts/commons/polyfills/custom_event.js

+/**
+ * Polyfill: CustomEvent constructor
+ * @what new CustomEvent()
+ * @why Certain features, e.g. notes utilize this
+ * @browsers Internet Explorer 11
+ * @see https://caniuse.com/#feat=customevent
+ */
 if (typeof window.CustomEvent !== 'function') {
   window.CustomEvent = function CustomEvent(event, params) {
     const evt = document.createEvent('CustomEvent');

app/assets/javascripts/commons/polyfills/element.js

-// polyfill Element.classList and DOMTokenList with classList.js
+/**
+ * Polyfill
+ * @what Element.classList
+ * @why In order to align browser features
+ * @browsers Internet Explorer 11
+ * @see https://caniuse.com/#feat=classlist
+ */
 import 'classlist-polyfill';
 
+/**
+ * Polyfill
+ * @what Element.closest
+ * @why In order to align browser features
+ * @browsers Internet Explorer 11
+ * @see https://caniuse.com/#feat=element-closest
+ */
 Element.prototype.closest =
   Element.prototype.closest ||
   function closest(selector, selectedElement = this) {
@@ -10,6 +23,13 @@ Element.prototype.closest =
       : Element.prototype.closest(selector, selectedElement.parentElement);
   };
 
+/**
+ * Polyfill
+ * @what Element.matches
+ * @why In order to align browser features
+ * @browsers Internet Explorer 11
+ * @see https://caniuse.com/#feat=mdn-api_element_matches
+ */
 Element.prototype.matches =
   Element.prototype.matches ||
   Element.prototype.matchesSelector ||
@@ -26,7 +46,15 @@ Element.prototype.matches =
     return i > -1;
   };
 
-// From the polyfill on MDN, https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/remove#Polyfill
+/**
+ * Polyfill
+ * @what ChildNode.remove, Element.remove, CharacterData.remove, DocumentType.remove
+ * @why In order to align browser features
+ * @browsers Internet Explorer 11
+ * @see https://caniuse.com/#feat=childnode-remove
+ *
+ * From the polyfill on MDN, https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/remove#Polyfill
+ */
 (arr => {
   arr.forEach(item => {
     if (Object.prototype.hasOwnProperty.call(item, 'remove')) {

app/assets/javascripts/commons/polyfills/event.js

 /**
- * Polyfill for IE11 support.
- * new Event() is not supported by IE11.
+ * Polyfill: Event constructor
+ * @what new Event()
+ * @why To align browser support
+ * @browsers Internet Explorer 11
+ * @see https://caniuse.com/#feat=mdn-api_event_event
+ *
  * Although `initEvent` is deprecated for modern browsers it is the one supported by IE
  */
 if (typeof window.Event !== 'function') {

app/assets/javascripts/commons/polyfills/nodelist.js

+/**
+ * Polyfill
+ * @what NodeList.forEach
+ * @why To align browser support
+ * @browsers Internet Explorer 11
+ * @see https://caniuse.com/#feat=mdn-api_nodelist_foreach
+ */
 if (window.NodeList && !NodeList.prototype.forEach) {
   NodeList.prototype.forEach = function forEach(callback, thisArg = window) {
     for (let i = 0; i < this.length; i += 1) {

app/assets/javascripts/commons/polyfills/request_idle_callback.js

+/**
+ * Polyfill
+ * @what requestIdleCallback
+ * @why To align browser features
+ * @browsers Safari (all versions), Internet Explorer 11
+ * @see https://caniuse.com/#feat=requestidlecallback
+ */
 window.requestIdleCallback =
   window.requestIdleCallback ||
   function requestShim(cb) {

app/assets/javascripts/commons/polyfills/svg.js

+/**
+ * polyfill support for external SVG file references via <use xlink:href>
+ * @what polyfill support for external SVG file references via <use xlink:href>
+ * @why This is used in our GitLab SVG icon library
+ * @browsers Internet Explorer 11
+ * @see https://caniuse.com/#feat=mdn-svg_elements_use_external_uri
+ * @see https//css-tricks.com/svg-use-external-source/
+ */
 import svg4everybody from 'svg4everybody';
 
-// polyfill support for external SVG file references via <use xlink:href>
-// @see https://css-tricks.com/svg-use-external-source/
 svg4everybody();