- Docs: Exclude from jsdoc firefox-extension, opera-widget, screencasts, test folders and build.html.js/rollup files

- Docs: Further JSDoc of methods
- Docs: Transfer some changes from ExtensionDocs on wiki (need to fully reconcile)
- Refactoring (minor): variadic args through ellipsis

editor/svg-editor.js

@@ -1432,11 +1432,16 @@ editor.init = function () {
     $(opt).addClass('current').siblings().removeClass('current');
   }
 
-  // This is a common function used when a tool has been clicked (chosen)
-  // It does several common things:
-  // - removes the tool_button_current class from whatever tool currently has it
-  // - hides any flyouts
-  // - adds the tool_button_current class to the button passed in
+  /**
+  * This is a common function used when a tool has been clicked (chosen)
+  * It does several common things:
+  * - removes the `tool_button_current` class from whatever tool currently has it
+  * - hides any flyouts
+  * - adds the `tool_button_current` class to the button passed in
+  * @param {String|Element} button The DOM element or string selector representing the toolbar button
+  * @param {Boolean} noHiding Whether not to hide any flyouts
+  * @returns {Boolean} Whether the button was disabled or not
+  */
   const toolButtonClick = editor.toolButtonClick = function (button, noHiding) {
     if ($(button).hasClass('disabled')) { return false; }
     if ($(button).parent().hasClass('tools_flyout')) { return true; }
@@ -1451,6 +1456,10 @@ editor.init = function () {
     return true;
   };
 
+  /**
+  * Unless the select toolbar button is disabled, sets the button
+  * and sets the select mode and cursor styles.
+  */
   const clickSelect = editor.clickSelect = function () {
     if (toolButtonClick('#tool_select')) {
       svgCanvas.setMode('select');
@@ -1458,6 +1467,10 @@ editor.init = function () {
     }
   };
 
+  /**
+  * Set a selected image's URL
+  * @param {String} url
+  */
   const setImageURL = editor.setImageURL = function (url) {
     if (!url) {
       url = defaultImageURL;
@@ -1658,6 +1671,10 @@ editor.init = function () {
     }
   }
 
+  /**
+  * @param center
+  * @param newCtr
+  */
   const updateCanvas = editor.updateCanvas = function (center, newCtr) {
     const zoom = svgCanvas.getZoom();
     const wArea = workarea;
@@ -3184,6 +3201,9 @@ editor.init = function () {
       }
     });
 
+    /**
+    * @param {Boolean} active
+    */
     editor.setPanning = function (active) {
       svgCanvas.spaceKey = keypan = active;
     };
@@ -3270,8 +3290,13 @@ editor.init = function () {
   }());
   // Made public for UI customization.
   // TODO: Group UI functions into a public editor.ui interface.
+  /**
+  * @param {Element|String} elem DOM Element or selector
+  * @param {Function} callback Mouseup callback
+  * @param {Boolean} dropUp
+  */
   editor.addDropDown = function (elem, callback, dropUp) {
-    if (!$(elem).length) { return; } // Quit if called on non-existant element
+    if (!$(elem).length) { return; } // Quit if called on non-existent element
     const button = $(elem).find('button');
     const list = $(elem).find('ul').attr('id', $(elem)[0].id + '-list');
     if (dropUp) {
@@ -3917,6 +3942,9 @@ editor.init = function () {
     hideDocProperties();
   };
 
+  /**
+  * Save user preferences based on current values in the UI
+  */
   const savePreferences = editor.savePreferences = function () {
     // Set background
     const color = $('#bg_blocks div.cur_background').css('background-color') || '#FFF';
@@ -4982,10 +5010,16 @@ editor.init = function () {
     }
   }, false);
 
+  /**
+  * Expose the uiStrings
+  */
   editor.canvas.getUIStrings = function () {
     return uiStrings;
   };
 
+  /**
+  * @param {Function} func Confirmation dialog callback
+  */
   editor.openPrep = function (func) {
     $('#main_menu').hide();
     if (undoMgr.getUndoStackSize() === 0) {
@@ -5125,6 +5159,10 @@ editor.init = function () {
   //  revnums += svgCanvas.getVersion();
   //  $('#copyright')[0].setAttribute('title', revnums);
 
+  /**
+  * @param {String} lang The language code
+  * @param {Object} allStrings
+  */
   const setLang = editor.setLang = function (lang, allStrings) {
     editor.langChanged = true;
     $.pref('lang', lang);
@@ -5194,6 +5232,12 @@ editor.init = function () {
   }
 };
 
+/**
+* Queues a callback to be invoked when the editor is ready (or
+*   to be invoked immediately if it is already ready)--i.e.,
+*   once all callbacks set by `svgEditor.runCallbacks` have been run
+* @param {Function} cb Callback to be queued to invoke
+*/
 editor.ready = function (cb) {
   if (!isReady) {
     callbacks.push(cb);
@@ -5202,6 +5246,9 @@ editor.ready = function (cb) {
   }
 };
 
+/**
+* Invokes the callbacks previous set by `svgEditor.ready`
+*/
 editor.runCallbacks = function () {
   // Todo: See if there is any benefit to refactoring some
   //   of the existing `editor.ready()` calls to return Promises
@@ -5212,12 +5259,19 @@ editor.runCallbacks = function () {
   });
 };
 
+/**
+* @param {String} str The SVG string to load
+*/
 editor.loadFromString = function (str) {
   editor.ready(function () {
     loadSvgString(str);
   });
 };
 
+/**
+* Not presently in use
+* @param featList
+*/
 editor.disableUI = function (featList) {
   // $(function () {
   //   $('#tool_wireframe, #tool_image, #main_button, #tool_source, #sidepanels').remove();
@@ -5225,6 +5279,10 @@ editor.disableUI = function (featList) {
   // });
 };
 
+/**
+* @param url URL from which to load an SVG string via Ajax
+* @param {Object} [opts] May contain properties: `cache`, `callback` (invoked with `true` or `false` depending on success)
+*/
 editor.loadFromURL = function (url, opts) {
   if (!opts) { opts = {}; }
 
@@ -5255,6 +5313,9 @@ editor.loadFromURL = function (url, opts) {
   });
 };
 
+/**
+* @param {String} str The Data URI to base64-decode (if relevant) and load
+*/
 editor.loadFromDataURI = function (str) {
   editor.ready(function () {
     let base64 = false;
@@ -5272,9 +5333,10 @@ editor.loadFromDataURI = function (str) {
   });
 };
 
-editor.addExtension = function () {
-  const args = arguments;
-
+/**
+* @param {...*} args Arguments to pass to `svgCanvas.addExtension` (though invoked on `svgEditor`)
+*/
+editor.addExtension = function (...args) {
   // Note that we don't want this on editor.ready since some extensions
   // may want to run before then (like server_opensave).
   // $(function () {

editor/svgcanvas.js

@@ -3217,8 +3217,15 @@ function getIssues ({codesOnly = false} = {}) {
   return issues;
 }
 
-// Generates a Data URL based on the current image, then calls "exported"
-// with an object including the string, image information, and any issues found
+/**
+* Generates a Data URL based on the current image, then calls "exported"
+* with an object including the string, image information, and any issues found
+* @param {String} [imgType="PNG"]
+* @param {Number} [quality] Between 0 and 1
+* @param {String} [exportWindowName]
+* @param {Function} [cb]
+* @returns {Promise}
+*/
 this.rasterExport = function (imgType, quality, exportWindowName, cb) {
   const mimeType = 'image/' + imgType.toLowerCase();
   const issues = getIssues();
@@ -3261,6 +3268,12 @@ this.rasterExport = function (imgType, quality, exportWindowName, cb) {
   });
 };
 
+/**
+* @param {String} exportWindowName
+* @param outputType Needed?
+* @param {Function} cb
+* @returns {Promise}
+*/
 this.exportPDF = function (exportWindowName, outputType, cb) {
   const that = this;
   return new Promise((resolve, reject) => {