incubator-senssoft-useralejs git commit: Added JSDoc DocBlock comments to document each function.

[rf...@apache.org]

Repository: incubator-senssoft-useralejs
Updated Branches:
  refs/heads/master bcb9b3637 -> c8ad449c4


Added JSDoc DocBlock comments to document each function.


Project: http://git-wip-us.apache.org/repos/asf/incubator-senssoft-useralejs/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-senssoft-useralejs/commit/c8ad449c
Tree: http://git-wip-us.apache.org/repos/asf/incubator-senssoft-useralejs/tree/c8ad449c
Diff: http://git-wip-us.apache.org/repos/asf/incubator-senssoft-useralejs/diff/c8ad449c

Branch: refs/heads/master
Commit: c8ad449c46a3b31352de2eb8b62d3a1419d8472a
Parents: bcb9b36
Author: Rob Foley <rg...@users.noreply.github.com>
Authored: Thu Jun 8 13:32:27 2017 -0400
Committer: Rob Foley <rg...@users.noreply.github.com>
Committed: Thu Jun 8 13:32:27 2017 -0400

----------------------------------------------------------------------
 src/attachHandlers.js     | 10 ++++++++++
 src/configure.js          | 11 +++++++++++
 src/getInitialSettings.js | 15 +++++++++++++++
 src/main.js               | 23 +++++++++++++++++++++++
 src/packageLogs.js        | 32 ++++++++++++++++++++++++++++++++
 src/sendLogs.js           | 23 +++++++++++++++++++++++
 6 files changed, 114 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-senssoft-useralejs/blob/c8ad449c/src/attachHandlers.js
----------------------------------------------------------------------
diff --git a/src/attachHandlers.js b/src/attachHandlers.js
index 55542f8..14f8525 100644
--- a/src/attachHandlers.js
+++ b/src/attachHandlers.js
@@ -22,6 +22,11 @@ var bufferBools;
 var bufferedEvents;
 var windowEvents;
 
+/**
+ * Defines the way information is extracted from various events.
+ * Also defines which events we will listen to.
+ * @param  {Object} config Configuration object to read from.
+ */
 export function defineDetails(config) {
   // Events list
   // Keys are event types
@@ -54,6 +59,11 @@ export function defineDetails(config) {
   windowEvents = ['load', 'blur', 'focus'];
 }
 
+/**
+ * Hooks the event handlers for each event type of interest.
+ * @param  {Object} config Configuration object to use.
+ * @return {boolean}        Whether the operation succeeded
+ */
 export function attachHandlers(config) {
   defineDetails(config);
 

http://git-wip-us.apache.org/repos/asf/incubator-senssoft-useralejs/blob/c8ad449c/src/configure.js
----------------------------------------------------------------------
diff --git a/src/configure.js b/src/configure.js
index d458fcc..32dc9ec 100644
--- a/src/configure.js
+++ b/src/configure.js
@@ -15,6 +15,12 @@
  * limitations under the License.
  */
 
+/**
+ * Shallow merges the first argument with the second.
+ * Retrieves/updates the userid if userFromParams is provided.
+ * @param  {Object} config    Current configuration object to be merged into.
+ * @param  {Object} newConfig Configuration object to merge into the current config.
+ */
 export function configure(config, newConfig) {
   Object.keys(newConfig).forEach(function(option) {
     if (option === 'userFromParams') {
@@ -27,6 +33,11 @@ export function configure(config, newConfig) {
   });
 }
 
+/**
+ * Attempts to extract the userid from the query parameters of the URL.
+ * @param  {string} param The name of the query parameter containing the userid.
+ * @return {string|null}       The extracted/decoded userid, or null if none is found.
+ */
 export function getUserIdFromParams(param) {
   var userField = param;
   var regex = new RegExp('[?&]' + userField + '(=([^&#]*)|&|#|$)');

http://git-wip-us.apache.org/repos/asf/incubator-senssoft-useralejs/blob/c8ad449c/src/getInitialSettings.js
----------------------------------------------------------------------
diff --git a/src/getInitialSettings.js b/src/getInitialSettings.js
index 42c7379..9794764 100644
--- a/src/getInitialSettings.js
+++ b/src/getInitialSettings.js
@@ -15,6 +15,11 @@
  * limitations under the License.
  */
 
+/**
+ * Extracts the initial configuration settings from the
+ * currently executing script tag.
+ * @return {Object} The extracted configuration object
+ */
 export function getInitialSettings() {
   var settings = {};
 
@@ -40,9 +45,19 @@ export function getInitialSettings() {
   return settings;
 }
 
+/**
+ * Creates a function to normalize the timestamp of the provided event.
+ * @param  {Object} e An event containing a timeStamp property.
+ * @return {timeStampScale~tsScaler}   The timestamp normalizing function.
+ */
 export function timeStampScale(e) {
   if (e.timeStamp && e.timeStamp > 0) {
     var delta = Date.now() - e.timeStamp;
+    /**
+     * Returns a timestamp depending on various browser quirks.
+     * @param  {?Number} ts A timestamp to use for normalization.
+     * @return {Number} A normalized timestamp.
+     */
     var tsScaler;
 
     if (delta < 0) {

http://git-wip-us.apache.org/repos/asf/incubator-senssoft-useralejs/blob/c8ad449c/src/main.js
----------------------------------------------------------------------
diff --git a/src/main.js b/src/main.js
index e1ab14a..da14d9e 100644
--- a/src/main.js
+++ b/src/main.js
@@ -38,6 +38,11 @@ if (config.autostart) {
   setup(config);
 }
 
+/**
+ * Hooks the global event listener, and starts up the
+ * logging interval.
+ * @param  {Object} config Configuration settings for the logger
+ */
 function setup(config) {
   if (!started) {
     setTimeout(function() {
@@ -58,6 +63,10 @@ function setup(config) {
 // Export the Userale API
 export var version = userAleVersion;
 
+/**
+ * Used to start the logging process if the
+ * autostart configuration option is set to false.
+ */
 export function start() {
   if (!started) {
     setup(config);
@@ -66,10 +75,19 @@ export function start() {
   config.on = true;
 }
 
+/**
+ * Halts the logging process. Logs will no longer be sent.
+ */
 export function stop() {
   config.on = false;
 }
 
+/**
+ * Updates the current configuration
+ * object with the provided values.
+ * @param  {Object} newConfig The configuration options to use.
+ * @return {Object}           Returns the updated configuration.
+ */
 export function options(newConfig) {
   if (newConfig !== undefined) {
     configure(config, newConfig);
@@ -78,6 +96,11 @@ export function options(newConfig) {
   return config;
 }
 
+/**
+ * Appends a log to the log queue.
+ * @param  {Object} customLog The log to append.
+ * @return {boolean}          Whether the operation succeeded.
+ */
 export function log(customLog) {
   if (customLog !== null && typeof customLog === 'object') {
     logs.push(customLog);

http://git-wip-us.apache.org/repos/asf/incubator-senssoft-useralejs/blob/c8ad449c/src/packageLogs.js
----------------------------------------------------------------------
diff --git a/src/packageLogs.js b/src/packageLogs.js
index 9e9b85a..9fa1156 100644
--- a/src/packageLogs.js
+++ b/src/packageLogs.js
@@ -18,11 +18,22 @@
 var logs;
 var config;
 
+/**
+ * Assigns the config and log container to be used by the logging functions.
+ * @param  {Array} newLogs   Log container.
+ * @param  {Object} newConfig Configuration to use while logging.
+ */
 export function initPackager(newLogs, newConfig) {
   logs = newLogs;
   config = newConfig;
 }
 
+/**
+ * Transforms the provided event into a log and appends it to the log container.
+ * @param  {Object} e         The event to be logged.
+ * @param  {Function} detailFcn The function to extract additional log parameters from the event.
+ * @return {boolean}           Whether the event was logged.
+ */
 export function packageLog(e, detailFcn) {
   if (!config.on) {
     return false;
@@ -52,6 +63,12 @@ export function packageLog(e, detailFcn) {
   return true;
 }
 
+/**
+ * Extracts coordinate information from the event
+ * depending on a few browser quirks.
+ * @param  {Object} e The event to extract coordinate information from.
+ * @return {Object}   An object containing nullable x and y coordinates for the event.
+ */
 export function getLocation(e) {
   if (e.pageX != null) {
     return { 'x' : e.pageX, 'y' : e.pageY };
@@ -62,6 +79,11 @@ export function getLocation(e) {
   }
 }
 
+/**
+ * Builds a string CSS selector from the provided element
+ * @param  {HTMLElement} ele The element from which the selector is built.
+ * @return {string}     The CSS selector for the element, or Unknown if it can't be determined.
+ */
 export function getSelector(ele) {
   if (ele.localName) {
     return ele.localName + (ele.id ? ('#' + ele.id) : '') + (ele.className ? ('.' + ele.className) : '');
@@ -74,6 +96,11 @@ export function getSelector(ele) {
   }
 }
 
+/**
+ * Builds an array of elements from the provided event target, to the root element.
+ * @param  {Object} e Event from which the path should be built.
+ * @return {HTMLElement[]}   Array of elements, starting at the event target, ending at the root element.
+ */
 export function buildPath(e) {
   var path = [];
   if (e.path) {
@@ -89,6 +116,11 @@ export function buildPath(e) {
   return selectorizePath(path);
 }
 
+/**
+ * Builds a CSS selector path from the provided list of elements.
+ * @param  {HTMLElement[]} path Array of HTMLElements from which the path should be built.
+ * @return {string[]}      Array of string CSS selectors.
+ */
 export function selectorizePath(path) {
   var i = 0;
   var pathEle;

http://git-wip-us.apache.org/repos/asf/incubator-senssoft-useralejs/blob/c8ad449c/src/sendLogs.js
----------------------------------------------------------------------
diff --git a/src/sendLogs.js b/src/sendLogs.js
index 7aa7323..c2516b9 100644
--- a/src/sendLogs.js
+++ b/src/sendLogs.js
@@ -15,11 +15,22 @@
  * limitations under the License.
  */
 
+/**
+ * Initializes the log queue processors.
+ * @param  {Array} logs   Array of logs to append to.
+ * @param  {Object} config Configuration object to use when logging.
+ */
 export function initSender(logs, config) {
   sendOnInterval(logs, config);
   sendOnClose(logs, config);
 }
 
+/**
+ * Checks the provided log array on an interval, flushing the logs
+ * if the queue has reached the threshold specified by the provided config.
+ * @param  {Array} logs   Array of logs to read from.
+ * @param  {Object} config Configuration object to be read from.
+ */
 export function sendOnInterval(logs, config) {
   setInterval(function() {
     if (logs.length >= config.logCountThreshold) {
@@ -29,6 +40,11 @@ export function sendOnInterval(logs, config) {
   }, config.transmitInterval);
 }
 
+/**
+ * Attempts to flush the remaining logs when the window is closed.
+ * @param  {Array} logs   Array of logs to be flushed.
+ * @param  {Object} config Configuration object to be read from.
+ */
 export function sendOnClose(logs, config) {
   if (navigator.sendBeacon) {
     window.addEventListener('unload', function() {
@@ -43,6 +59,13 @@ export function sendOnClose(logs, config) {
   }
 }
 
+/**
+ * Sends the provided array of logs to the specified url,
+ * retrying the request up to the specified number of retries.
+ * @param  {Array} logs    Array of logs to send.
+ * @param  {string} url     URL to send the POST request to.
+ * @param  {Number} retries Maximum number of attempts to send the logs.
+ */
 export function sendLogs(logs, url, retries) {
   var req = new XMLHttpRequest();