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 <rgfo...@users.noreply.github.com> Authored: Thu Jun 8 13:32:27 2017 -0400 Committer: Rob Foley <rgfo...@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();