Merge pull request #103 from woocommerce/update/tracking-jsdoc-deps

Upgrade the npm dependency `jsdoc` to v4 for the JS package `tracking-jsdoc`

packages/js/jsdoc/.jsdocrc.dev.json

@@ -0,0 +1,17 @@
+{
+  "plugins": [
+    "./tilde-alias",
+    "../tracking-jsdoc/fires-description",
+    "jsdoc-plugin-typescript",
+    "jsdoc-advanced-types-plugin",
+    "jsdoc-plugin-intersection"
+  ],
+  "typescript": {
+    "moduleRoot": "../../../samples/jsdoc"
+  },
+  "templates": {
+    "woocommerce-grow-tracking-jsdoc": {
+      "path": "../../../samples/jsdoc/TRACKING.md"
+    }
+  }
+}

packages/js/jsdoc/README.md

@@ -55,7 +55,7 @@ Plugins implemented elsewhere, that are bundled here for easier use
 
 ### Event emitters descriptions
 [`woocommerce-grow-tracking-jsdoc/fires-description`](https://github.com/woocommerce/grow/tree/add/jsdoc/packages/js/tracking-jsdoc#emitters)
-To document what or when is emitted with `@fires` or `@emmits`.
+To document what or when is emitted with `@fires` or `@emits`.
 #### Imported types
 `jsdoc-plugin-typescript`
 

packages/js/jsdoc/package.json

@@ -15,6 +15,9 @@
   "bin": {
     "woocommerce-grow-jsdoc": "bin/jsdoc.mjs"
   },
+  "scripts": {
+    "dev:doc:tracking": "jsdoc ../../../samples/jsdoc -c ./.jsdocrc.dev.json -t ../tracking-jsdoc"
+  },
   "dependencies": {
     "jsdoc": "^3.6.10",
     "jsdoc-advanced-types-plugin": "git+https://github.com/tomalec/jsdoc-advanced-types-plugin#add/return-support",

packages/js/tracking-jsdoc/README.md

@@ -39,12 +39,12 @@ You may add any of the following properties to your JSDoc config (`.jsdocrc.json
 Then make sure `jsdoc` uses it, by `jsdoc -r your/source/files/ -c .jsdocrc.json`.
 
 ## Emitters
-If you would like to add some descriptions to `@fires` or `@emmits` tags, for example to specify what data is attached to the event, add `fires-description` to your plugins list:
+If you would like to add some descriptions to `@fires` or `@emits` tags, for example to specify what data is attached to the event, add `fires-description` to your plugins list:
 
 ```json
 {
   "plugins": [
-    // To be able to add descriptions to `@fires` & `@emmits`
+    // To be able to add descriptions to `@fires` & `@emits`
     "woocommerce-grow-tracking-jsdoc/fires-description"
   ],
   // …

packages/js/tracking-jsdoc/fires-description.js

@@ -1,21 +1,19 @@
 /**
- * JSDoc plugin that allows to use descriptions for built-in `@fires` & `@emmits` tags.
+ * JSDoc plugin that allows to use descriptions for built-in `@fires` & `@emits` tags.
  *
  * Overwrites the standard definition with `canHaveName: true` option,
  * and tweaks `applyNamespace` to apply it only to `value.name`.
  */
 const { applyNamespace } = require( 'jsdoc/name' );
 
 exports.defineTags = function ( dictionary ) {
-	dictionary
-		.defineTag( 'fires', {
-			mustHaveValue: true,
-			canHaveName: true,
-			onTagged( doclet, tag ) {
-				doclet.fires = doclet.fires || [];
-				tag.value.name = applyNamespace( tag.value.name, 'event' );
-				doclet.fires.push( tag.value );
-			},
-		} )
-		.synonym( ' emmits' );
+	dictionary.defineTag( 'fires', {
+		mustHaveValue: true,
+		canHaveName: true,
+		onTagged( doclet, tag ) {
+			doclet.fires = doclet.fires || [];
+			tag.value.name = applyNamespace( tag.value.name, 'event' );
+			doclet.fires.push( tag.value );
+		},
+	} );
 };

packages/js/tracking-jsdoc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "woocommerce-grow-tracking-jsdoc",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "JSDoc template to report Tracking events to markdown file",
   "repository": {
     "type": "git",
@@ -13,6 +13,6 @@
   },
   "homepage": "https://github.com/woocommerce/grow#readme",
   "peerDependencies": {
-    "jsdoc": "^3.6.10"
+    "jsdoc": "^4.0.2"
   }
 }

packages/js/tracking-jsdoc/publish.js

@@ -37,7 +37,7 @@ function getLineLink( symbol, readmeDir ) {
 /**
  * Generate documentation output.
  *
- * @param {Object} data A TaffyDB collection representing
+ * @param {Object} data A Salty instance representing
  *                      all the symbols documented in your code.
  */
 exports.publish = function ( data ) {
@@ -60,9 +60,11 @@ exports.publish = function ( data ) {
 
 	let mdResult = '';
 
+	data.sort( 'name' );
+
 	data( { kind: 'event' } )
-		.order( 'name' )
-		.each( ( symbol ) => {
+		.get()
+		.forEach( ( symbol ) => {
 			// Build the event title with the link to its source.
 			mdResult += `\n### ${ getLineLink( symbol, readmeDir ) }\n`;
 			// description
@@ -94,8 +96,11 @@ exports.publish = function ( data ) {
 
 			// Find all places that fires the event.
 			const emitters = new Map();
-			// TaffyDB#has is buggy https://github.com/typicaljoe/taffydb/issues/19, so let's filter it manually.
-			data( { fires: { isArray: true } } ).each( ( emitter ) => {
+			const matchFires = function () {
+				return Array.isArray( this.fires );
+			};
+
+			data( matchFires ).each( ( emitter ) => {
 				const firesCurrent = emitter.fires.filter(
 					( fires ) => fires.name === 'event:' + symbol.name
 				);

samples/jsdoc/.eslintrc.js

@@ -0,0 +1,10 @@
+module.exports = {
+	settings: {
+		jsdoc: {
+			tagNamePreference: {
+				// Allows the non-preferred synonym tag name of `@fires`
+				emits: 'emits',
+			},
+		},
+	},
+};

samples/jsdoc/Component.js

@@ -0,0 +1,35 @@
+/*
+ * ============================================================================
+ * For validating the `fires-description` plugin and `publish` template in the
+ * JS package `tracking-jsdoc` in this repo.
+ * ============================================================================
+ */
+
+/**
+ * Modal to greet the user, after successful completion of onboarding.
+ *
+ * @fires modal_closed with `action: 'create-paid-campaign' | 'maybe-later' | 'view-product-feed' | 'dismiss'`
+ * @emits modal_opened with `context: GUIDE_NAMES.SUBMISSION_SUCCESS`
+ */
+export const SuccessGuide = () => {
+	return 1;
+};
+
+/**
+ * Renders `DateRangeFilterPicker`, handles range selection, fires applicable track events.
+ *
+ * @fires datepicker_update with `report: props.trackEventReportId` and `data` given by `DateRangeFilterPicker`'s `onRangeSelect` callback.
+ */
+export const DatepickerStartDate = () => {
+	return 1;
+};
+
+/**
+ * Set of filters to be used in Programs Report page.
+ * Contains date and program pickers.
+ *
+ * @emits datepicker_update
+ */
+export default function DatepickerEndDate() {
+	return 1;
+}

samples/jsdoc/TRACKING.md

@@ -0,0 +1,51 @@
+# Usage Tracking
+
+Some nice general description.
+
+<woocommerce-grow-tracking-jsdoc>
+<!---
+Everything below will be automatically generated by `woocommerce-grow-tracking-jsdoc`.
+Do not edit it manually!
+-->
+
+### [`datepicker_update`](eventTracks.js#L20)
+Triggered when datepicker (date ranger picker) is updated,
+ with report name and data that comes from `DateRangeFilterPicker`'s `onRangeSelect` callback
+#### Properties
+| name | type | description |
+| ---- | ---- | ----------- |
+`report` | `string` | eport  Name of the report (e.g. `"dashboard" \| "reports-programs" \| "reports-products" \| "product-feed"`)
+`country` | `module:eventTracks~CountryCode` | Value selected in datepicker.
+`compare` | `string` | mpare Value selected in datepicker.
+`period` | `string` | eriod  Value selected in datepicker.
+`before` | `module:eventTracks~DateTime` | ore  Value selected in datepicker.
+`after` | `module:eventTracks~DateTime` | ter   Value selected in datepicker.
+#### Emitters
+- [`DatepickerStartDate`](Component.js#L23) with `report: props.trackEventReportId` and `data` given by `DateRangeFilterPicker`'s `onRangeSelect` callback.
+- [`exports`](Component.js#L33)
+
+### [`modal_closed`](eventTracks.js#L40)
+A modal is closed.
+#### Properties
+| name | type | description |
+| ---- | ---- | ----------- |
+`context` | `string` | Indicates which modal is closed
+`action` | `string` | Indicates the modal is closed by what action (e.g. `maybe-later`\|`dismiss` \| `create-another-campaign`)                             - `maybe-later` is used when the "Maybe later" button on the modal is clicked                             - `dismiss` is used when the modal is dismissed by clicking on "X" icon, overlay, generic "Cancel" button, or pressing ESC                             - `create-another-campaign` is used when the button "Create another campaign" is clicked                             - `create-paid-campaign` is used when the button "Create paid campaign" is clicked                             - `confirm` is used when the button "Confirm", "Save"  or similar generic "Accept" button is clicked
+#### Emitters
+- [`SuccessGuide`](Component.js#L14) with `action: 'create-paid-campaign' | 'maybe-later' | 'view-product-feed' | 'dismiss'`
+
+### [`modal_opened`](eventTracks.js#L33)
+A modal is opened.
+#### Properties
+| name | type | description |
+| ---- | ---- | ----------- |
+`context` | `string` | Indicates which modal is open
+#### Emitters
+- [`SuccessGuide`](Component.js#L14) with `context: GUIDE_NAMES.SUBMISSION_SUCCESS`
+
+<!---
+End of `woocommerce-grow-tracking-jsdoc`-generated content.
+-->
+</woocommerce-grow-tracking-jsdoc>
+
+More nice general description.

samples/jsdoc/eventTracks.js

@@ -0,0 +1,51 @@
+/*
+ * ============================================================================
+ * For validating the `tilde-alias` plugin in the JS package `jsdoc` in this
+ * repo.
+ * ============================================================================
+ */
+
+/**
+ * @typedef {import('~/types').CountryCode} CountryCode
+ * @typedef {import('.~/types').DateTime} DateTime
+ */
+
+/*
+ * ============================================================================
+ * For validating the `fires-description` plugin and `publish` template in the
+ * JS package `tracking-jsdoc` in this repo.
+ * ============================================================================
+ */
+
+/**
+ * Triggered when datepicker (date ranger picker) is updated,
+ * with report name and data that comes from `DateRangeFilterPicker`'s `onRangeSelect` callback
+ *
+ * @event datepicker_update
+ * @property {string}      report  Name of the report (e.g. `"dashboard" | "reports-programs" | "reports-products" | "product-feed"`)
+ * @property {CountryCode} country Value selected in datepicker.
+ * @property {string}      compare Value selected in datepicker.
+ * @property {string}      period  Value selected in datepicker.
+ * @property {DateTime}    before  Value selected in datepicker.
+ * @property {DateTime}    after   Value selected in datepicker.
+ */
+
+/**
+ * A modal is opened.
+ *
+ * @event modal_opened
+ * @property {string} context Indicates which modal is open
+ */
+
+/**
+ * A modal is closed.
+ *
+ * @event modal_closed
+ * @property {string} context Indicates which modal is closed
+ * @property {string} action  Indicates the modal is closed by what action (e.g. `maybe-later`|`dismiss` | `create-another-campaign`)
+ *                            - `maybe-later` is used when the "Maybe later" button on the modal is clicked
+ *                            - `dismiss` is used when the modal is dismissed by clicking on "X" icon, overlay, generic "Cancel" button, or pressing ESC
+ *                            - `create-another-campaign` is used when the button "Create another campaign" is clicked
+ *                            - `create-paid-campaign` is used when the button "Create paid campaign" is clicked
+ *                            - `confirm` is used when the button "Confirm", "Save"  or similar generic "Accept" button is clicked
+ */

samples/jsdoc/types.js

@@ -0,0 +1,21 @@
+/*
+ * ============================================================================
+ * For validating the `tilde-alias` plugin in the JS package `jsdoc` in this
+ * repo.
+ * ============================================================================
+ */
+
+/**
+ * CountryCode
+ *
+ * @typedef {string} CountryCode Two-letter country code in ISO 3166-1 alpha-2 format.
+ */
+
+/**
+ * DateTime
+ *
+ * @typedef {string} CountryCode Date string in ISO 8601 format.
+ */
+
+// This export is required for JSDoc in other files to import the type definitions from this file.
+export default {};