docs: Add options.js to jsdoc and reference website (#327)

* clean and reorganize website scripts

* Add jsdoc to options.js

* Add Options.md to sidebar

Co-authored-by: Kelson Warner <[email protected]>

Author: jooohhn

package.json

@@ -65,12 +65,9 @@
     "test": "make test",
     "dev": "node test/browser/server.js",
     "docs:install": "cd website/ && yarn install",
-    "docs:generate-jsdoc": "node website/generate-jsdoc",
+    "docs:generate-jsdoc": "cd website && yarn generate-jsdoc",
     "docs:start": "cd website/ && yarn start",
-    "docs:build": "cd website/ && yarn build",
-    "docs:serve": "cd website/ && yarn serve",
-    "docs:deploy": "cd website/ && yarn deploy",
-    "docs:swizzle": "cd website/ && yarn swizzle"
+    "docs:deploy": "cd website/ && yarn deploy"
   },
   "bugs": {
     "url": "https://github.com/amplitude/amplitude-javascript/issues"

src/amplitude-client.js

@@ -74,7 +74,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 [options.js](https://github.com/amplitude/Amplitude-JavaScript/blob/master/src/options.js#L14) for list of options and default values.
+ * See [options.js](https://amplitude.github.io/Amplitude-JavaScript/Options) for a 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'); });
  */

src/options.js

@@ -11,6 +11,43 @@ if (BUILD_COMPAT_REACT_NATIVE) {
   }
 }
 
+/**
+ * Options used when initializing Amplitude
+ * @typedef {Object} Options
+ * @property {string} [apiEndpoint=`api.amplitude.com`] - Endpoint to send amplitude event requests to.
+ * @property {boolean} [batchEvents=`false`] -  If `true`, then events are batched together and uploaded only when the number of unsent events is greater than or equal to eventUploadThreshold or after eventUploadPeriodMillis milliseconds have passed since the first unsent event was logged.
+ * @property {number} [cookieExpiration=`365`] - The number of days after which the Amplitude cookie will expire. 12 months is for GDPR compliance.
+ * @property {string} [cookieName=`amplitude_id`] - *DEPRECATED*
+ * @property {string} [sameSiteCookie='None'] -  Sets the SameSite flag on the amplitude cookie. Decides cookie privacy policy.
+ * @property {boolean} [cookieForceUpgrade=`false`] - Forces pre-v6.0.0 instances to adopt post-v6.0.0 compat cookie formats.
+ * @property {boolean} [deferInitialization=`null`] -  If `true`, disables the core functionality of the sdk, including saving a cookie and all logging, until explicitly enabled. To enable tracking, please call `amplitude.getInstance().enableTracking()` *Note: This will not affect users who already have an amplitude cookie. The decision to track events is determined by whether or not a user has an amplitude analytics cookie. If the `cookieExpiration</code> is manually defined to be a short lifespan, you may need to run `amplitude.getInstance().enableTracking()` upon the cookie expiring or upon logging in.*
+ * @property {boolean} [disableCookies=`false`] -  Disable Ampllitude cookies altogether.
+ * @property {string} [deviceId=A randomly generated UUID.] -  The custom Device ID to set. *Note: This is not recommended unless you know what you are doing (e.g. you have your own system for tracking user devices).*
+ * @property {boolean} [deviceIdFromUrlParam=`false`] -  If `true`, then the SDK will parse Device ID values from the URL parameter amp_device_id if available. Device IDs defined in the configuration options during init will take priority over Device IDs from URL parameters.
+ * @property {string} [domain=The top domain of the current page's URL. ('https://amplitude.com')] -  Set a custom domain for the Amplitude cookie. To include subdomains, add a preceding period, eg: `.amplitude.com`.
+ * @property {number} [eventUploadPeriodMillis=`30000` (30 sec)] -  Amount of time in milliseconds that the SDK waits before uploading events if batchEvents is true.
+ * @property {number} [eventUploadThreshold=`30`] -  Minimum number of events to batch together per request if batchEvents is true.
+ * @property {boolean} [forceHttps=`true`] -  If `true`, the events will always be uploaded to HTTPS endpoint. Otherwise, it will use the embedding site's protocol.
+ * @property {boolean} [includeGclid=`false`] -  If `true`, captures the gclid URL parameter as well as the user's initial_gclid via a setOnce operation.
+ * @property {boolean} [includeReferrer=`false`] -  If `true`, captures the referrer and referring_domain for each session, as well as the user's initial_referrer and initial_referring_domain via a setOnce operation.
+ * @property {boolean} [includeUtm=`false`] -  If `true`, finds UTM parameters in the query string or the _utmz cookie, parses, and includes them as user properties on all events uploaded. This also captures initial UTM parameters for each session via a setOnce operation.
+ * @property {string} [language=The language determined by the browser] -  Custom language to set.
+ * @property {string} [logLevel=`WARN`] -  Level of logs to be printed in the developer console. Valid values are 'DISABLE', 'ERROR', 'WARN', 'INFO'. To learn more about the different options, see below.
+ * @property {boolean} [logAttributionCapturedEvent=`false`] - If `true`, the SDK will log an Amplitude event anytime new attribution values are captured from the user. **Note: These events count towards your event volume.** Event name being logged: [Amplitude] Attribution Captured. Event Properties that can be logged: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `referrer`, `referring_domain`, `gclid`. For UTM properties to be logged, `includeUtm` must be set to `true`. For the `referrer` and `referring_domain` properties to be logged, `includeReferrer` must be set to `true`. For the `gclid` property to be logged, `includeGclid` must be set to `true`.
+ * @property {boolean} [optOut=`false`] -  Whether or not to disable tracking for the current user.
+ * @property {function} [onError=`() => {}`] - Function to call on error.
+ * @property {string} [platform=`Web`|`iOS`|`Android`] -  Platform device is running on. `Web` is a browser (including mobile browsers). `iOS` and `Android` are relevant only for react-native apps.
+ * @property {number} [savedMaxCount=`1000`] -  Maximum number of events to save in localStorage. If more events are logged while offline, then old events are removed.
+ * @property {boolean} [saveEvents=`true`] -  If `true`, saves events to localStorage and removes them upon successful upload. *Note: Without saving events, events may be lost if the user navigates to another page before the events are uploaded.*
+ * @property {boolean} [saveParamsReferrerOncePerSession=`true`] -  If `true`, then includeGclid, includeReferrer, and includeUtm will only track their respective properties once per session. New values that come in during the middle of the user's session will be ignored. Set to false to always capture new values.
+ * @property {boolean} [secureCookie=`false`] -  If `true`, the amplitude cookie will be set with the Secure flag.
+ * @property {number} [sessionTimeout=`30*60*1000` (30 min)] -  The time between logged events before a new session starts in milliseconds.
+ * @property {Object} [trackingOptions=`{ city: true, country: true, carrier: true, device_manufacturer: true, device_model: true, dma: true, ip_address: true, language: true, os_name: true, os_version: true, platform: true, region: true, version_name: true}`] - Type of data associated with a user.
+ * @property {boolean} [unsetParamsReferrerOnNewSession=`false`] -  If `false`, the existing `referrer` and `utm_parameter` values will be carried through each new session. If set to `true`, the `referrer` and `utm_parameter` user properties, which include `referrer`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, and `utm_content`, will be set to `null` upon instantiating a new session. Note: This only works if includeReferrer or includeUtm includeUtm are set to `true`.
+ * @property {string} [unsentKey=`amplitude_unsent`] - localStorage key that stores unsent events.
+ * @property {string} [unsentIdentifyKey=`amplitude_unsent_identify`] - localStorage key that stores unsent identifies.
+ * @property {number} [uploadBatchSize=`100`] -  The maximum number of events to send to the server per request.
+ */
 export default {
   apiEndpoint: 'api.amplitude.com',
   batchEvents: false,

website/.gitignore

@@ -13,6 +13,7 @@ docs/Amplitude.md
 docs/AmplitudeClient.md
 docs/Identify.md
 docs/Revenue.md
+docs/Options.md
 
 # Misc
 .DS_Store

website/generate-jsdoc.js

@@ -2,15 +2,32 @@ const jsdoc2md = require("jsdoc-to-markdown");
 const fs = require("fs");
 const path = require("path");
 const prettier = require("prettier");
-const publicFiles = [
+const publicClassFiles = [
   "amplitude-client.js",
   "amplitude.js",
   "identify.js",
   "revenue.js",
 ];
+const publicTypedefFiles = ["options.js"];
 const srcDir = path.join(__dirname, "../", "src");
 const outputDir = path.join(__dirname, "docs");
-function generateMarkdown(inputFile) {
+
+function generateTypedefMarkdown(inputFile) {
+  const inputFilePath = path.join(srcDir, inputFile);
+  const data = jsdoc2md.getTemplateDataSync({ files: inputFilePath });
+  const name = data.find((e) => e.kind === "typedef").name;
+  const filteredData = data.filter((e) => e.kind === "typedef");
+  const outputFilePath = path.join(outputDir, `${name}.md`);
+  const markdownOutput = filteredData
+    .map((item) => documentOptionsFile(item))
+    .join("\n");
+  fs.writeFileSync(
+    path.join(outputDir, `${name}.md`),
+    prettier.format(markdownOutput, { parser: "mdx" })
+  );
+}
+
+function generateClassMarkdown(inputFile) {
   const inputFilePath = path.join(srcDir, inputFile);
   const data = jsdoc2md.getTemplateDataSync({ files: inputFilePath });
   const className = data.find((e) => e.kind === "class").name;
@@ -22,15 +39,38 @@ function generateMarkdown(inputFile) {
   const outputFilePath = path.join(outputDir, `${className}.md`);
 
   const markdownOutput = filteredData
-    .map((item) => documentItem(item))
+    .map((item) => documentClassFile(item))
     .join("\n");
   fs.writeFileSync(
     path.join(outputDir, `${className}.md`),
     prettier.format(markdownOutput, { parser: "mdx" })
   );
 }
 
-function documentItem(data) {
+function documentOptionsFile(data) {
+  return `${documentHeader(data)}
+  
+  ${data.description}
+
+Option | Type | Description |	Default
+-------|------|-------------|---------
+${documentOptionsProperties(data)}
+
+`;
+}
+
+function documentOptionsProperties(data) {
+  return data.properties
+    .map(
+      (prop) =>
+        `${prop.name || ""} | ${data.properties[0].type.names.join("|")} | ${
+          prop.defaultvalue || ""
+        } | ${prop.description || ""}`
+    )
+    .join("\n");
+}
+
+function documentClassFile(data) {
   return `${documentHeader(data)}
 
 ${data.examples ? documentExamples(data) : ""}
@@ -46,9 +86,8 @@ ${data.returns ? documentReturn(data) : ""}
 }
 
 function documentHeader(data) {
-  if (data.deprecated)
-    return `## ~~\`${data.id}\`~~`
-  return `## \`${data.id}\``
+  if (data.deprecated) return `## ~~\`${data.id}\`~~`;
+  return `## \`${data.id}\``;
 }
 
 function documentExamples(data) {
@@ -67,7 +106,7 @@ function documentDeprecated(data) {
 
 function documentParams(data) {
   const params = data.params.map(
-    (param) => `- \`${param.name}\` (\`${param.type.names.join('|')}\`)
+    (param) => `- \`${param.name}\` (\`${param.type.names.join("|")}\`)
 ${param.description}
 `
   );
@@ -78,15 +117,22 @@ ${params.join("\n")}
 
 function documentReturn(data) {
   return `### Return Value
-- (\`${data.returns[0].type.names.join('|')}\`)
+- (\`${data.returns[0].type.names.join("|")}\`)
 ${data.returns[0].description}
 `;
 }
 
+// Main Script
+
 if (!fs.existsSync(outputDir)) {
   fs.mkdirSync(outputDir);
 }
 
-for (const file of publicFiles) {
-  generateMarkdown(file);
+for (const file of publicClassFiles) {
+  generateClassMarkdown(file);
 }
+
+for (const file of publicTypedefFiles) {
+  generateTypedefMarkdown(file);
+}
+

website/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
+    "generate-jsdoc": "node generate-jsdoc",
     "start": "docusaurus start",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",

website/sidebars.js

@@ -1,5 +1,5 @@
 module.exports = {
   sidebar: {
-    'API Reference': ['AmplitudeClient', 'Amplitude', 'Identify', 'Revenue'],
+    'API Reference': ['AmplitudeClient', 'Amplitude', 'Identify', 'Revenue', 'Options'],
   },
 };