Improve code documentation

chrome/js/settings.js

@@ -6,18 +6,31 @@
 
 'use strict';
 
+/**
+ * Page event aggregator.
+ *
+ * @var {Object} vent
+ */
 var vent = {};
 
+/**
+ * Fires at the end of the document loading process.
+ */
 window.onload = function () {
 
     let controls = document.querySelectorAll('[data-setting-id]');
 
     for (var index = 0, control; control = controls[index]; index++) {
-        control.addEventListener('change', handleSettingChange);
+        control.addEventListener('change', handleSettingAlteration);
     }
 };
 
-function handleSettingChange ({ target }) {
+/**
+ * Fires once a setting value has been altered.
+ *
+ * @property {Event} event A representation of a DOM event.
+ */
+function handleSettingAlteration ({ target }) {
 
     let settingId, previousValue, currentValue;
 
@@ -25,17 +38,20 @@ function handleSettingChange ({ target }) {
     previousValue = target.getAttribute('data-previous-value') || null;
     currentValue = target.value;
 
+    // Apply the setting to the user interface.
     applySetting({
         id: settingId,
         value: currentValue
     });
 
+    // Inform the attached content script.
     vent.emit('setting:altered', {
         settingId: settingId,
         previousValue: previousValue,
         currentValue: currentValue
     });
 
+    // Memorize the previous value of the setting.
     target.setAttribute('data-previous-value', currentValue);
 }
 
@@ -101,7 +117,6 @@ function applySetting (setting) {
  * https://bugzilla.mozilla.org/show_bug.cgi?id=787351
  *
  * @param {Object} l10n A localization object.
- * @private
  */
 function applyL10n (l10n) {
 

src/main.js

@@ -116,12 +116,15 @@ function showSettingsPanel () {
 
     if (settingsTab === null) {
 
+        // Open up the settings panel in a new tab.
         tabBrowser.addTab(SETTINGS_URI, {
             selected: true,
             parentId: tabBrowser.selectedTab.id
         });
 
     } else {
+
+        // Activate an existing settings panel tab.
         tabBrowser.selectTab(settingsTab);
     }
 }