Fix docs (#293)

* fix multiple param/return types generation

* fix dead links

* clean up docs spacing and content

* fix deprecated notes in amplitude.js

* Add style support for deprecated docs

* Add admonitions

Author: jooohhn

src/amplitude-client.js

@@ -70,7 +70,7 @@ AmplitudeClient.prototype.Revenue = Revenue;
  * @param {string} apiKey - The API key for your app.
  * @param {string} opt_userId - (optional) An identifier for this user.
  * @param {object} opt_config - (optional) Configuration options.
- * See [Readme]{@link https://github.com/amplitude/Amplitude-Javascript#configuration-options} for list of options and default values.
+ * See [options.js](https://github.com/amplitude/Amplitude-JavaScript/blob/master/src/options.js#L14) for list of options and default values.
  * @param {function} opt_callback - (optional) Provide a callback function to run after initialization is complete.
  * @example amplitudeClient.init('API_KEY', 'USER_ID', {includeReferrer: true, includeUtm: true}, function() { alert('init complete'); });
  */
@@ -858,12 +858,14 @@ AmplitudeClient.prototype.setUserId = function setUserId(userId) {
 
 /**
  * Add user to a group or groups. You need to specify a groupType and groupName(s).
+ * 
  * For example you can group people by their organization.
- * In that case groupType is "orgId" and groupName would be the actual ID(s).
+ * In that case, groupType is "orgId" and groupName would be the actual ID(s).
  * groupName can be a string or an array of strings to indicate a user in multiple gruups.
  * You can also call setGroup multiple times with different groupTypes to track multiple types of groups (up to 5 per app).
+ * 
  * Note: this will also set groupType: groupName as a user property.
- * See the [SDK Readme]{@link https://github.com/amplitude/Amplitude-Javascript#setting-groups} for more information.
+ * See the [advanced topics article](https://developers.amplitude.com/docs/setting-user-groups) for more information.
  * @public
  * @param {string} groupType - the group type (ex: orgId)
  * @param {string|list} groupName - the name of the group (ex: 15), or a list of names of the groups
@@ -1034,8 +1036,8 @@ var _convertProxyObjectToRealObject = function _convertProxyObjectToRealObject(i
 
 /**
  * Send an identify call containing user property operations to Amplitude servers.
- * See [Readme]{@link https://github.com/amplitude/Amplitude-Javascript#user-properties-and-user-property-operations}
- * for more information on the Identify API and user property operations.
+ * See the [Identify](https://amplitude.github.io/Amplitude-JavaScript/Identify/)
+ * reference page for more information on the Identify API and user property operations.
  * @param {Identify} identify_obj - the Identify object containing the user property operations to send.
  * @param {Amplitude~eventCallback} opt_callback - (optional) callback function to run when the identify event has been sent.
  * Note: the server response code and response body from the identify event upload are passed to the callback function.
@@ -1344,7 +1346,8 @@ AmplitudeClient.prototype.logEventWithTimestamp = function logEvent(eventType, e
  * Log an event with eventType, eventProperties, and groups. Use this to set event-level groups.
  * Note: the group(s) set only apply for the specific event type being logged and does not persist on the user
  * (unless you explicitly set it with setGroup).
- * See the [SDK Readme]{@link https://github.com/amplitude/Amplitude-Javascript#setting-groups} for more information
+ * 
+ * See the [advanced topics article](https://developers.amplitude.com/docs/setting-user-groups) for more information.
  * about groups and Count by Distinct on the Amplitude platform.
  * @public
  * @param {string} eventType - name of event
@@ -1385,8 +1388,9 @@ var _isNumber = function _isNumber(n) {
 /**
  * Log revenue with Revenue interface. The new revenue interface allows for more revenue fields like
  * revenueType and event properties.
- * See [Readme]{@link https://github.com/amplitude/Amplitude-Javascript#tracking-revenue}
- * for more information on the Revenue interface and logging revenue.
+ * 
+ * See the [Revenue](https://amplitude.github.io/Amplitude-JavaScript/Revenue/)
+ * reference page for more information on the Revenue interface and logging revenue.
  * @public
  * @param {Revenue} revenue_obj - the revenue object containing the revenue data being logged.
  * @example var revenue = new amplitude.Revenue().setProductId('productIdentifier').setPrice(10.99);

src/amplitude.js

@@ -8,11 +8,15 @@ import { version } from '../package.json';
 import DEFAULT_OPTIONS from './options';
 
 /**
- * Legacy API of Amplitude SDK - instance manager. Wraps around the current amplitude-client.js which provides more features
+ * Deprecated legacy API of the Amplitude JS SDK - instance manager.
+ * 
+ * Wraps around the current [AmplitudeClient](https://amplitude.github.io/Amplitude-JavaScript/) which provides more features
  * Function calls directly on amplitude have been deprecated. Please call methods on the default shared instance: amplitude.getInstance() instead.
- * See [Readme]{@link https://github.com/amplitude/Amplitude-Javascript#300-update-and-logging-events-to-multiple-amplitude-apps} for more information about this change.
+ * 
+ * See the [3.0.0 changelog](https://github.com/amplitude/Amplitude-JavaScript/blob/ed405afb5f06d5cf5b72539a5d09179abcf7e1fe/README.md#300-update-and-logging-events-to-multiple-amplitude-apps) for more information about this change.
  * @constructor Amplitude
  * @public
+ * @deprecated
  * @example var amplitude = new Amplitude();
  */
 var Amplitude = function Amplitude() {
@@ -66,7 +70,7 @@ if (BUILD_COMPAT_2_0) {
    * @param {string} apiKey - The API key for your app.
    * @param {string} opt_userId - (optional) An identifier for this user.
    * @param {object} opt_config - (optional) Configuration options.
-   * See [Readme]{@link https://github.com/amplitude/Amplitude-Javascript#configuration-options} for list of options and default values.
+   * See [options.js](https://github.com/amplitude/Amplitude-JavaScript/blob/master/src/options.js#L14) for list of options and default values.
    * @param {function} opt_callback - (optional) Provide a callback function to run after initialization is complete.
    * @deprecated Please use amplitude.getInstance().init(apiKey, opt_userId, opt_config, opt_callback);
    * @example amplitude.init('API_KEY', 'USER_ID', {includeReferrer: true, includeUtm: true}, function() { alert('init complete'); });
@@ -163,7 +167,7 @@ if (BUILD_COMPAT_2_0) {
    * groupName can be a string or an array of strings to indicate a user in multiple gruups.
    * You can also call setGroup multiple times with different groupTypes to track multiple types of groups (up to 5 per app).
    * Note: this will also set groupType: groupName as a user property.
-   * See the [SDK Readme]{@link https://github.com/amplitude/Amplitude-Javascript#setting-groups} for more information.
+   * See the [advanced topics article](https://developers.amplitude.com/docs/setting-user-groups) for more information.
    * @public
    * @param {string} groupType - the group type (ex: orgId)
    * @param {string|list} groupName - the name of the group (ex: 15), or a list of names of the groups
@@ -199,7 +203,9 @@ if (BUILD_COMPAT_2_0) {
 
   /**
     * Sets a custom deviceId for current user. Note: this is not recommended unless you know what you are doing
-    * (like if you have your own system for managing deviceIds). Make sure the deviceId you set is sufficiently unique
+    * (like if you have your own system for managing deviceIds).
+    * 
+    * Make sure the deviceId you set is sufficiently unique
     * (we recommend something like a UUID - see src/uuid.js for an example of how to generate) to prevent conflicts with other devices in our system.
     * @public
     * @param {string} deviceId - custom deviceId for current user.
@@ -213,10 +219,10 @@ if (BUILD_COMPAT_2_0) {
   /**
    * Sets user properties for the current user.
    * @public
-   * @param {object} - object with string keys and values for the user properties to set.
-   * @param {boolean} - DEPRECATED opt_replace: in earlier versions of the JS SDK the user properties object was kept in
+   * @param {object} userProperties - object with string keys and values for the user properties to set.
+   * @param {boolean} opt_replace - Deprecated. In earlier versions of the JS SDK the user properties object was kept in
    * memory and replace = true would replace the object in memory. Now the properties are no longer stored in memory, so replace is deprecated.
-   * @deprecated Please use amplitude.getInstance.setUserProperties(userProperties);
+   * @deprecated Please use amplitude.getInstance().setUserProperties(userProperties);
    * @example amplitude.setUserProperties({'gender': 'female', 'sign_up_complete': true})
    */
   Amplitude.prototype.setUserProperties = function setUserProperties(userProperties) {
@@ -235,8 +241,8 @@ if (BUILD_COMPAT_2_0) {
 
   /**
    * Send an identify call containing user property operations to Amplitude servers.
-   * See [Readme]{@link https://github.com/amplitude/Amplitude-Javascript#user-properties-and-user-property-operations}
-   * for more information on the Identify API and user property operations.
+   * See the [Identify](https://amplitude.github.io/Amplitude-JavaScript/Identify/)
+   * reference page for more information on the Identify API and user property operations.
    * @param {Identify} identify_obj - the Identify object containing the user property operations to send.
    * @param {Amplitude~eventCallback} opt_callback - (optional) callback function to run when the identify event has been sent.
    * Note: the server response code and response body from the identify event upload are passed to the callback function.
@@ -284,9 +290,11 @@ if (BUILD_COMPAT_2_0) {
 
   /**
    * Log an event with eventType, eventProperties, and groups. Use this to set event-level groups.
+   * 
    * Note: the group(s) set only apply for the specific event type being logged and does not persist on the user
    * (unless you explicitly set it with setGroup).
-   * See the [SDK Readme]{@link https://github.com/amplitude/Amplitude-Javascript#setting-groups} for more information
+   * 
+   * See the [advanced topics article](https://developers.amplitude.com/docs/setting-user-groups) for more information.
    * about groups and Count by Distinct on the Amplitude platform.
    * @public
    * @param {string} eventType - name of event
@@ -295,7 +303,7 @@ if (BUILD_COMPAT_2_0) {
    * groupName can be a string or an array of strings.
    * @param {Amplitude~eventCallback} opt_callback - (optional) a callback function to run after the event is logged.
    * Note: the server response code and response body from the event upload are passed to the callback function.
-   * Deprecated Please use amplitude.getInstance().logEventWithGroups(eventType, eventProperties, groups, opt_callback);
+   * @deprecated Please use amplitude.getInstance().logEventWithGroups(eventType, eventProperties, groups, opt_callback);
    * @example amplitude.logEventWithGroups('Clicked Button', null, {'orgId': 24});
    */
   Amplitude.prototype.logEventWithGroups = function(eventType, eventProperties, groups, opt_callback) {
@@ -305,8 +313,9 @@ if (BUILD_COMPAT_2_0) {
   /**
    * Log revenue with Revenue interface. The new revenue interface allows for more revenue fields like
    * revenueType and event properties.
-   * See [Readme]{@link https://github.com/amplitude/Amplitude-Javascript#tracking-revenue}
-   * for more information on the Revenue interface and logging revenue.
+   * 
+   * See the [Revenue](https://amplitude.github.io/Amplitude-JavaScript/Revenue/)
+   * reference page for more information on the Revenue interface and logging revenue.
    * @public
    * @param {Revenue} revenue_obj - the revenue object containing the revenue data being logged.
    * @deprecated Please use amplitude.getInstance().logRevenueV2(revenue_obj);
@@ -318,7 +327,7 @@ if (BUILD_COMPAT_2_0) {
   };
 
   /**
-   * Log revenue event with a price, quantity, and product identifier. DEPRECATED - use logRevenueV2
+   * Log revenue event with a price, quantity, and product identifier.
    * @public
    * @param {number} price - price of revenue event
    * @param {number} quantity - (optional) quantity of products in revenue event. If no quantity specified default to 1.
@@ -350,9 +359,9 @@ if (BUILD_COMPAT_2_0) {
   };
 
   /**
-   * Set global user properties. Note this is deprecated, and we recommend using setUserProperties
+   * Set global user properties.
    * @public
-   * @deprecated
+   * @deprecated Please use amplitudeClient.setUserProperties
    */
   Amplitude.prototype.setGlobalUserProperties = function setGlobalUserProperties(userProperties) {
     this.getInstance().setUserProperties(userProperties);

src/identify.js

@@ -21,8 +21,6 @@ var AMP_OP_UNSET = '$unset';
  * allowing you to chain multiple method calls together.
  * Note: if the same user property is used in multiple operations on a single Identify object,
  * only the first operation on that property will be saved, and the rest will be ignored.
- * See [Readme]{@link https://github.com/amplitude/Amplitude-Javascript#user-properties-and-user-property-operations}
- * for more information on the Identify API and user property operations.
  * @constructor Identify
  * @public
  * @example var identify = new amplitude.Identify();

src/revenue.js

@@ -2,19 +2,13 @@ import constants from './constants';
 import type from './type';
 import utils from './utils';
 
-/*
- * Wrapper for logging Revenue data. Revenue objects get passed to amplitude.logRevenueV2 to send to Amplitude servers.
- * Note: price is the only required field. If quantity is not specified, then defaults to 1.
- */
-
 /**
- * Revenue API - instance constructor. Revenue objects are a wrapper for revenue data.
+ * Revenue API - instance constructor. Wrapper for logging Revenue data. Revenue objects get passed to amplitude.logRevenueV2 to send to Amplitude servers.
  * Each method updates a revenue property in the Revenue object, and returns the same Revenue object,
  * allowing you to chain multiple method calls together.
+ * 
  * Note: price is a required field to log revenue events.
  * If quantity is not specified then defaults to 1.
- * See [Readme]{@link https://github.com/amplitude/Amplitude-Javascript#tracking-revenue} for more information
- * about logging Revenue.
  * @constructor Revenue
  * @public
  * @example var revenue = new amplitude.Revenue();
@@ -68,7 +62,8 @@ Revenue.prototype.setQuantity = function setQuantity(quantity) {
 
 /**
  * Set a value for the price. This field is required for all revenue being logged.
- * Note revenue amount is calculated as price * quantity.
+ * 
+ * Note: revenue amount is calculated as price * quantity.
  * @public
  * @param {number} price - Double value for the quantity.
  * @return {Revenue} Returns the same Revenue object, allowing you to chain multiple method calls together.

website/generate-jsdoc.js

@@ -26,33 +26,48 @@ function generateMarkdown(inputFile) {
     .join("\n");
   fs.writeFileSync(
     path.join(outputDir, `${className}.md`),
-    prettier.format(markdownOutput, { parser: "markdown" })
+    prettier.format(markdownOutput, { parser: "mdx" })
   );
 }
 
 function documentItem(data) {
-  return `## \`${data.id}\`
+  return `${documentHeader(data)}
 
 ${data.examples ? documentExamples(data) : ""}
 
 ${data.description || ""} 
 
+${data.deprecated ? documentDeprecated(data) : ""}
+
 ${data.params ? documentParams(data) : ""}
 
 ${data.returns ? documentReturn(data) : ""}
 `;
 }
 
+function documentHeader(data) {
+  if (data.deprecated)
+    return `## ~~\`${data.id}\`~~`
+  return `## \`${data.id}\``
+}
+
 function documentExamples(data) {
   return `\`\`\`
 ${data.examples}
 \`\`\`
 `;
 }
 
+function documentDeprecated(data) {
+  return `:::danger Deprecated
+  ${data.deprecated}
+  :::
+`;
+}
+
 function documentParams(data) {
   const params = data.params.map(
-    (param) => `- \`${param.name}\` (\`${param.type.names[0]}\`)
+    (param) => `- \`${param.name}\` (\`${param.type.names.join('|')}\`)
 ${param.description}
 `
   );
@@ -63,7 +78,7 @@ ${params.join("\n")}
 
 function documentReturn(data) {
   return `### Return Value
-- (\`${data.returns[0].type.names[0]}\`)
+- (\`${data.returns[0].type.names.join('|')}\`)
 ${data.returns[0].description}
 `;
 }

website/src/css/custom.css

@@ -14,6 +14,7 @@
   --ifm-color-primary-light: #48a4de;
   --ifm-color-primary-lighter: #7bbee7;
   --ifm-color-primary-lightest: #c6e2f4;
+  --ifm-color-danger: #E71829;
   --ifm-code-font-size: 95%;
 }
 
@@ -23,32 +24,3 @@
   margin: 0 calc(-1 * var(--ifm-pre-padding));
   padding: 0 var(--ifm-pre-padding);
 }
-
-/* OG site color #10069f */
-/* logo color #007fd2 */
-/* sidebar dark #003b61 */
-/* sidebar darkest #0c2a4b */
-/* Sidebar text ##c6d0d9 */
-
-/* $cerulean-50: #f4faff;
-$cerulean-100: #e4f1fa;
-$cerulean-200: #c6e2f4;
-$cerulean-300: #7bbee7;
-$cerulean-400: #48a4de;
-$cerulean-500: #007fd2;
-$cerulean-600: #0065a5;
-$cerulean-700: #005488;
-$cerulean-800: #003b61;
-$cerulean-900: #0c2a4b;
-:export {
-  cerulean-50: $cerulean-50;
-  cerulean-100: $cerulean-100;
-  cerulean-200: $cerulean-200;
-  cerulean-300: $cerulean-300;
-  cerulean-400: $cerulean-400;
-  cerulean-500: $cerulean-500;
-  cerulean-600: $cerulean-600;
-  cerulean-700: $cerulean-700;
-  cerulean-800: $cerulean-800;
-  cerulean-900: $cerulean-900;
-} */