Add documentation to @snowplow/browser-tracker (close snowplow#939)

Author: Paul Boocock

.github/workflows/build.yml

@@ -81,7 +81,7 @@ jobs:
       - name: Upload plugins
         uses: actions/upload-artifact@v2
         with:
-          name: plugins-umd
+          name: plugins.umd
           path: |
             ./plugins/*/dist/*.umd.js
             ./plugins/*/dist/*.umd.js.map

.gitignore

@@ -63,6 +63,7 @@ common/deploy/
 common/temp/
 common/autoinstallers/*/.npmrc
 **/.rush/temp/
+trackers/browser-tracker/temp/
 
 # Distribution files
 dist

libraries/browser-tracker-core/src/helpers.ts

@@ -48,7 +48,7 @@ export interface FilterCriterion<T> {
 
 /**
  * Checks if an object is a string
- * @param str The object to check
+ * @param str - The object to check
  */
 export function isString(str: Object): str is string {
   if (str && typeof str.valueOf() === 'string') {
@@ -59,7 +59,7 @@ export function isString(str: Object): str is string {
 
 /**
  * Checks if an object is an integer
- * @param int The object to check
+ * @param int - The object to check
  */
 export function isInteger(int: Object): int is number {
   return (
@@ -69,7 +69,7 @@ export function isInteger(int: Object): int is number {
 
 /**
  * Checks if the input parameter is a function
- * @param func The object to check
+ * @param func - The object to check
  */
 export function isFunction(func: unknown) {
   if (func && typeof func === 'function') {
@@ -127,7 +127,7 @@ export function fixupDomain(domain: string) {
  * in the old URL. It will be returned unless overriden
  * by a "refer(r)er" parameter in the querystring.
  *
- * @param string oldLocation Optional.
+ * @param string - oldLocation Optional.
  * @return string The referrer
  */
 export function getReferrer(oldLocation?: string) {
@@ -198,9 +198,9 @@ export function fromQuerystring(field: string, url: string) {
 /**
  * Add a name-value pair to the querystring of a URL
  *
- * @param string url URL to decorate
- * @param string name Name of the querystring pair
- * @param string value Value of the querystring pair
+ * @param string - url URL to decorate
+ * @param string - name Name of the querystring pair
+ * @param string - value Value of the querystring pair
  */
 export function decorateQuerystring(url: string, name: string, value: string) {
   var initialQsParams = name + '=' + value;
@@ -234,7 +234,7 @@ export function decorateQuerystring(url: string, name: string, value: string) {
 /**
  * Attempt to get a value from localStorage
  *
- * @param string key
+ * @param string - key
  * @return string The value obtained from localStorage, or
  *                undefined if localStorage is inaccessible
  */
@@ -257,9 +257,9 @@ export function attemptGetLocalStorage(key: string) {
 /**
  * Attempt to write a value to localStorage
  *
- * @param string key
- * @param string value
- * @param number ttl Time to live in seconds, defaults to 2 years from Date.now()
+ * @param string - key
+ * @param string - value
+ * @param number - ttl Time to live in seconds, defaults to 2 years from Date.now()
  * @return boolean Whether the operation succeeded
  */
 export function attemptWriteLocalStorage(key: string, value: string, ttl = 63072000) {
@@ -277,7 +277,7 @@ export function attemptWriteLocalStorage(key: string, value: string, ttl = 63072
 /**
  * Attempt to delete a value from localStorage
  *
- * @param string key
+ * @param string - key
  * @return boolean Whether the operation succeeded
  */
 export function attemptDeleteLocalStorage(key: string) {
@@ -294,7 +294,7 @@ export function attemptDeleteLocalStorage(key: string) {
 /**
  * Attempt to get a value from sessionStorage
  *
- * @param string key
+ * @param string - key
  * @return string The value obtained from sessionStorage, or
  *                undefined if sessionStorage is inaccessible
  */
@@ -309,8 +309,8 @@ export function attemptGetSessionStorage(key: string) {
 /**
  * Attempt to write a value to sessionStorage
  *
- * @param string key
- * @param string value
+ * @param string - key
+ * @param string - value
  * @return boolean Whether the operation succeeded
  */
 export function attemptWriteSessionStorage(key: string, value: string) {
@@ -356,8 +356,8 @@ export function findRootDomain(sameSite: string, secure: boolean) {
 /**
  * Checks whether a value is present within an array
  *
- * @param val The value to check for
- * @param array The array to check within
+ * @param val - The value to check for
+ * @param array - The array to check within
  * @return boolean Whether it exists
  */
 export function isValueInArray<T>(val: T, array: T[]) {
@@ -372,8 +372,8 @@ export function isValueInArray<T>(val: T, array: T[]) {
 /**
  * Deletes an arbitrary cookie by setting the expiration date to the past
  *
- * @param cookieName The name of the cookie to delete
- * @param domainName The domain the cookie is in
+ * @param cookieName - The name of the cookie to delete
+ * @param domainName - The domain the cookie is in
  */
 export function deleteCookie(cookieName: string, domainName?: string, sameSite?: string, secure?: boolean) {
   cookie(cookieName, '', -1, '/', domainName, sameSite, secure);
@@ -382,7 +382,7 @@ export function deleteCookie(cookieName: string, domainName?: string, sameSite?:
 /**
  * Fetches the name of all cookies beginning with a certain prefix
  *
- * @param cookiePrefix The prefix to check for
+ * @param cookiePrefix - The prefix to check for
  * @return array The cookies that begin with the prefix
  */
 export function getCookiesWithPrefix(cookiePrefix: string) {
@@ -400,13 +400,13 @@ export function getCookiesWithPrefix(cookiePrefix: string) {
  * Get and set the cookies associated with the current document in browser
  * This implementation always returns a string, returns the cookie value if only name is specified
  *
- * @param name The cookie name (required)
- * @param value The cookie value
- * @param ttl The cookie Time To Live (seconds)
- * @param path The cookies path
- * @param domain The cookies domain
- * @param samesite The cookies samesite attribute
- * @param secure Boolean to specify if cookie should be secure
+ * @param name - The cookie name (required)
+ * @param value - The cookie value
+ * @param ttl - The cookie Time To Live (seconds)
+ * @param path - The cookies path
+ * @param domain - The cookies domain
+ * @param samesite - The cookies samesite attribute
+ * @param secure - Boolean to specify if cookie should be secure
  * @return string The cookies value
  */
 export function cookie(
@@ -437,7 +437,7 @@ export function cookie(
  * Parses an object and returns either the
  * integer or undefined.
  *
- * @param obj The object to parse
+ * @param obj - The object to parse
  * @return the result of the parse operation
  */
 export function parseAndValidateInt(obj: unknown) {
@@ -449,7 +449,7 @@ export function parseAndValidateInt(obj: unknown) {
  * Parses an object and returns either the
  * number or undefined.
  *
- * @param obj The object to parse
+ * @param obj - The object to parse
  * @return the result of the parse operation
  */
 export function parseAndValidateFloat(obj: unknown) {
@@ -460,10 +460,10 @@ export function parseAndValidateFloat(obj: unknown) {
 /**
  * Convert a criterion object to a filter function
  *
- * @param object criterion Either {allowlist: [array of allowable strings]}
+ * @param object - criterion Either {allowlist: [array of allowable strings]}
  *                             or {denylist: [array of allowable strings]}
  *                             or {filter: function (elt) {return whether to track the element}
- * @param boolean byClass Whether to allowlist/denylist based on an element's classes (for forms)
+ * @param boolean - byClass Whether to allowlist/denylist based on an element's classes (for forms)
  *                        or name attribute (for fields)
  */
 export function getFilterByClass(criterion?: FilterCriterion<HTMLElement> | null): (elt: HTMLElement) => boolean {
@@ -485,7 +485,7 @@ export function getFilterByClass(criterion?: FilterCriterion<HTMLElement> | null
 /**
  * Convert a criterion object to a filter function
  *
- * @param object criterion Either {allowlist: [array of allowable strings]}
+ * @param object - criterion Either {allowlist: [array of allowable strings]}
  *                             or {denylist: [array of allowable strings]}
  *                             or {filter: function (elt) {return whether to track the element}
  */

libraries/browser-tracker-core/src/snowplow.ts

@@ -38,8 +38,8 @@ const namedTrackers: Record<string, BrowserTracker> = {};
 /**
  * Dispatch function to all specified trackers
  *
- * @param trackers An optional list of trackers to send the event to, or will send to all trackers
- * @param fn The function which will run against each tracker
+ * @param trackers - An optional list of trackers to send the event to, or will send to all trackers
+ * @param fn - The function which will run against each tracker
  */
 export function dispatchToTrackers(trackers: Array<string> | undefined, fn: (t: BrowserTracker) => void) {
   try {
@@ -52,9 +52,9 @@ export function dispatchToTrackers(trackers: Array<string> | undefined, fn: (t:
 /**
  * Dispatch function to all specified trackers from the supplied collection
  *
- * @param trackers An optional list of trackers to send the event to, or will send to all trackers
- * @param trackerCollection The collection which the trackers will be selected from
- * @param fn The function which will run against each tracker
+ * @param trackers - An optional list of trackers to send the event to, or will send to all trackers
+ * @param trackerCollection - The collection which the trackers will be selected from
+ * @param fn - The function which will run against each tracker
  */
 export function dispatchToTrackersInCollection(
   trackers: Array<string> | undefined,
@@ -70,20 +70,20 @@ export function dispatchToTrackersInCollection(
 
 /**
  * Checks if a tracker has been created for a particular identifier
- * @param trackerId The unique identifier of the tracker
+ * @param trackerId - The unique identifier of the tracker
  */
 export function trackerExists(trackerId: string) {
   return namedTrackers.hasOwnProperty(trackerId);
 }
 
 /**
  * Creates a Tracker and adds it to the internal collection
- * @param trackerId The unique identifier of the tracker
- * @param namespace The namespace of the tracker, tracked with each event as `tna`
- * @param version The current version of the tracker library
- * @param endpoint The endpoint to send events to
- * @param sharedState The instance of shared state to use for this tracker
- * @param configuration The configuration to use for this tracker instance
+ * @param trackerId - The unique identifier of the tracker
+ * @param namespace - The namespace of the tracker, tracked with each event as `tna`
+ * @param version - The current version of the tracker library
+ * @param endpoint - The endpoint to send events to
+ * @param sharedState - The instance of shared state to use for this tracker
+ * @param configuration - The configuration to use for this tracker instance
  */
 export function addTracker(
   trackerId: string,
@@ -102,7 +102,7 @@ export function addTracker(
 
 /**
  * Gets a single instance of the internal tracker object
- * @param trackerId The unique identifier of the tracker
+ * @param trackerId - The unique identifier of the tracker
  * @returns The tracker instance, or null if not found
  */
 export function getTracker(trackerId: string) {
@@ -116,7 +116,7 @@ export function getTracker(trackerId: string) {
 
 /**
  * Gets an array of tracker instances based on the list of identifiers
- * @param trackerIds An array of unique identifiers of the trackers
+ * @param trackerIds - An array of unique identifiers of the trackers
  * @returns The tracker instances, or empty list if none found
  */
 export function getTrackers(trackerIds: Array<string>): Array<BrowserTracker> {

libraries/browser-tracker-core/src/tracker/index.ts

@@ -106,12 +106,12 @@ type ActivityTrackingConfig = {
 /**
  * The Snowplow Tracker
  *
- * @param trackerId The unique identifier of the tracker
- * @param namespace The namespace of the tracker object
- * @param version The current version of the JavaScript Tracker
- * @param endpoint The collector endpoint to send events to, with or without protocol
- * @param sharedState An object containing state which is shared across tracker instances
- * @param trackerConfiguration Dictionary of configuration options
+ * @param trackerId - The unique identifier of the tracker
+ * @param namespace - The namespace of the tracker object
+ * @param version - The current version of the JavaScript Tracker
+ * @param endpoint - The collector endpoint to send events to, with or without protocol
+ * @param sharedState - An object containing state which is shared across tracker instances
+ * @param trackerConfiguration - Dictionary of configuration options
  */
 export function Tracker(
   trackerId: string,
@@ -319,7 +319,7 @@ export function Tracker(
     /**
      * Decorate the querystring of a single link
      *
-     * @param event e The event targeting the link
+     * @param event - e The event targeting the link
      */
     function linkDecorationHandler(evt: Event) {
       var timestamp = new Date().getTime();
@@ -334,7 +334,7 @@ export function Tracker(
      * Whenever such a link is clicked on or navigated to via the keyboard,
      * add "_sp={{duid}}.{{timestamp}}" to its querystring
      *
-     * @param crossDomainLinker Function used to determine which links to decorate
+     * @param crossDomainLinker - Function used to determine which links to decorate
      */
     function decorateLinks(crossDomainLinker: (elt: HTMLAnchorElement | HTMLAreaElement) => boolean) {
       for (var i = 0; i < document.links.length; i++) {
@@ -751,7 +751,7 @@ export function Tracker(
     /**
      * Adds the protocol in front of our collector URL
      *
-     * @param string collectorUrl The collector URL with or without protocol
+     * @param string - collectorUrl The collector URL with or without protocol
      * @returns string collectorUrl The tracker URL with protocol
      */
     function asCollectorUrl(collectorUrl: string) {
@@ -853,8 +853,8 @@ export function Tracker(
     /**
      * Combine an array of unchanging contexts with the result of a context-creating function
      *
-     * @param staticContexts Array of custom contexts
-     * @param contextCallback Function returning an array of contexts
+     * @param staticContexts - Array of custom contexts
+     * @param contextCallback - Function returning an array of contexts
      */
     function finalizeContexts(
       staticContexts?: Array<SelfDescribingJson> | null,