More doc updates

plugins/browser-plugin-element-tracking/README.md

@@ -30,16 +30,22 @@ npm install @snowplow/browser-plugin-element-tracking
 
 ## Usage
 
-Initialize your tracker with the SnowplowMediaPlugin:
+Initialize your tracker with the SnowplowElementTrackingPlugin and then call `startElementTracking`:
 
 ```js
 import { newTracker } from '@snowplow/browser-tracker';
-import { SnowplowElementTrackingPlugin } from '@snowplow/browser-plugin-element-tracking';
+import { SnowplowElementTrackingPlugin, startElementTracking } from '@snowplow/browser-plugin-element-tracking';
 
 newTracker('sp1', '{{collector_url}}', {
    appId: 'my-app-id',
    plugins: [ SnowplowElementTrackingPlugin() ],
 });
+
+startElementTracking({
+   elements: [
+      {selector: '.newsletter-signup'}
+   ]
+});
 ```
 
 For a full API reference, you can read the plugin [documentation page](https://docs.snowplow.io/docs/collecting-data/collecting-from-own-applications/javascript-trackers/browser-tracker/browser-tracker-v3-reference/plugins/element-tracking/).

plugins/browser-plugin-element-tracking/src/api.ts

@@ -285,7 +285,7 @@ const detailedComponentGenerator = baseComponentGenerator.bind(null, true, confi
  *
  * If a `cb` function is provided, it is called with the above generators as parameters that it can use in asynchronous situations (such as the JavaScript tracker).
  *
- * @param cb
+ * @param cb Callback function to receive the generator callbacks described above asynchronously.
  * @returns Array of callbacks described above.
  */
 export function getComponentListGenerator(

plugins/browser-plugin-element-tracking/src/components.ts

@@ -3,6 +3,14 @@ import { getElementDetails } from './data';
 import { ComponentsEntity, ElementDetailsEntity, Entities } from './schemata';
 import { nodeIsElement } from './util';
 
+/**
+ * Generic callback for providing `component` entities for given Elements.
+ * Auto discovers element and name from parameters and returns the list of components that encapsulate that element.
+ * @param withDetails Whether details for each component should be included.
+ * @param configurations List of configurations that contain component definitions.
+ * @param params Arbitrary parameters that should include an element and optionally a logical name for that element.
+ * @returns `component_parents` entity, or if `withDetails` specified, a list of entities containing `component_parents` and the details for each component as `element` entities.
+ */
 export const baseComponentGenerator = (
   withDetails: boolean,
   configurations: Configuration[],

plugins/browser-plugin-element-tracking/src/data.ts

@@ -55,7 +55,7 @@ export function isDataSelector(val: unknown): val is DataSelector {
  * @param element Element to select data from
  * @param path The CSS path used to select `element`, which may be requested by the `selector`
  * @param selectors The list of DataSelectors to evaluate
- * @returns
+ * @returns Flattened list of results found processing the element.
  */
 export function extractSelectorDetails(element: Element, path: string, selectors: DataSelector[]): AttributeList {
   return selectors.reduce((attributes: AttributeList, selector) => {
@@ -238,12 +238,12 @@ export function buildContentTree(
 
 /**
  * Builds an `element` entity.
- * @param config
- * @param element
- * @param rect
- * @param position
- * @param matches
- * @returns
+ * @param config Configuration describing any additional data that should be included in the entity.
+ * @param element The elment this entity will describe.
+ * @param rect The position/dimension information of the element.
+ * @param position Which match this element is amongst those that match the Configuration's selector.
+ * @param matches The total number, including this one, of elements that matched the Configuration selector.
+ * @returns The Element entity SDJ.
  */
 export function getElementDetails(
   config: Configuration,

plugins/browser-plugin-element-tracking/src/util.ts

@@ -1,5 +1,10 @@
 import { Configuration } from './configuration';
 
+/**
+ * Parses custom boundaries config.
+ * @param boundaryPixels Input format boundaries.
+ * @returns Object describing the input boundary configuration.
+ */
 export function defineBoundaries(boundaryPixels: number | [number, number] | [number, number, number, number]) {
   let boundTop: number, boundRight: number, boundBottom: number, boundLeft: number;
   if (typeof boundaryPixels === 'number') {
@@ -20,6 +25,13 @@ export function defineBoundaries(boundaryPixels: number | [number, number] | [nu
   return { boundTop, boundRight, boundBottom, boundLeft };
 }
 
+/**
+ * Gets descendent elements of `target` (`document` by default) that match the selector info in `config`.
+ * This is usually a wrapper around `querySelectorAll`, but accounts for shadow roots that can be specified in `config`.
+ * @param config The configuration containing the selector and other details that influence how elements will be found.
+ * @param target The root to start finding descendent elements from; defaults to `document`
+ * @returns Array of elements within `target` that matched the configuration in `config`.
+ */
 export function getMatchingElements(config: Configuration, target: ParentNode = document) {
   const { selector, shadowOnly, shadowSelector } = config;
   const elements: Element[] = shadowOnly ? [] : Array.from(target.querySelectorAll(selector));
@@ -38,6 +50,11 @@ export function getMatchingElements(config: Configuration, target: ParentNode =
   return elements;
 }
 
+/**
+ * Type guard to check that `Node` is an `Element`
+ * @param node Node to check.
+ * @returns If `node` is an Element.
+ */
 export function nodeIsElement(node: Node): node is Element {
   return node.nodeType === Node.ELEMENT_NODE;
 }