From b726217fab0edccd17bdd74ee8920ed07d020023 Mon Sep 17 00:00:00 2001
From: Zack Stickles <zstickles@gmail.com>
Date: Mon, 17 Aug 2020 15:05:15 -0700
Subject: [PATCH] feat: added ability to add supplemental documentation

---
 src/data/additionalDocs.js | 51 +++++++++++++++++++++++++++++++
 src/hooks/useApiDoc.js     | 61 ++++++++++++++++++++++++--------------
 2 files changed, 89 insertions(+), 23 deletions(-)
 create mode 100644 src/data/additionalDocs.js

diff --git a/src/data/additionalDocs.js b/src/data/additionalDocs.js
new file mode 100644
index 000000000..2230d7663
--- /dev/null
+++ b/src/data/additionalDocs.js
@@ -0,0 +1,51 @@
+const additionalDocs = {
+  nerdlet: {
+    methods: [
+      {
+        name: 'nerdlet.setUrlState',
+        description: `
+Updates the current nerdlet's URL state that can be read from
+\`NerdletStateContext.Consumer\`.
+
+If you wish to update nerdlet's state without persisting its value in the
+url, use React's built-in \`setState()\`.
+
+This method behaves like React's \`setState()\`, meaning that it performs a
+shallow merge between the current URL state and the provided state in the
+\`urlState\` parameter.
+
+If you wish to navigate without adding an entry to the browser history, set
+\`urlStateOptions.replaceHistory\` to \`true\`.
+        `.trim(),
+        returnValue: { type: 'void' },
+        params: [
+          {
+            name: 'urlState',
+            type: 'Object',
+            description: 'New nerdlet URL state.',
+          },
+          {
+            name: 'urlStateOptions',
+            type: 'UrlStateOptions',
+            description: 'Options for the URL state.',
+          },
+        ],
+        examples: [
+          {
+            label: 'Example 1',
+            sourceCode: `
+nerlet.setUrlState({
+  foo: 'bar',
+});
+            `.trim(),
+            options: {
+              live: false,
+            },
+          },
+        ],
+      },
+    ],
+  },
+};
+
+export default additionalDocs;
diff --git a/src/hooks/useApiDoc.js b/src/hooks/useApiDoc.js
index 078517f76..c34c9b390 100644
--- a/src/hooks/useApiDoc.js
+++ b/src/hooks/useApiDoc.js
@@ -1,6 +1,7 @@
 import { useMemo } from 'react';
 import { getTypeDefs } from '../utils/typeDefs';
 import navigationApi from '../data/navigationApi';
+import additionalDocs from '../data/additionalDocs';
 
 const IGNORED_METHODS = [
   'prototype',
@@ -34,6 +35,15 @@ const useApiDoc = (name) => {
       return navigationApi;
     }
 
+    // The SDK may be missing method documentation. If so, we need to add in
+    // some additional hardcoded values.
+    const clientDocs = {
+      typeDefs: [],
+      constants: [],
+      methods: [],
+      ...additionalDocs[name],
+    };
+
     if (!api) {
       const err = new Error('NR1_SDK API not found');
       window.NREUM && window.NREUM.noticeError(err, { apiName: name });
@@ -65,30 +75,35 @@ const useApiDoc = (name) => {
     return {
       description: apiDocs?.text,
       usage: `import { ${name} } from 'nr1'`,
-      typeDefs: getTypeDefs(properties),
-      constants: getConstants(api),
-      methods: Object.getOwnPropertyNames(api)
-        .filter(
-          (member) =>
-            !IGNORED_METHODS.includes(member) &&
-            typeof api[member] === 'function'
-        )
-        .filter(
-          (member) =>
-            !IGNORED_METHODS_BY_LIB[name] ||
-            !IGNORED_METHODS_BY_LIB[name].includes(member)
-        )
-        .map((member) => {
-          const methodDocs = api[member].__docs__;
+      typeDefs: [...clientDocs.typeDefs, ...getTypeDefs(properties)],
+      constants: [...clientDocs.constants, ...getConstants(api)],
+      methods: [
+        ...clientDocs.methods,
+        ...Object.getOwnPropertyNames(api)
+          .filter(
+            (member) =>
+              !IGNORED_METHODS.includes(member) &&
+              typeof api[member] === 'function'
+          )
+          .filter(
+            (member) =>
+              !IGNORED_METHODS_BY_LIB[name] ||
+              !IGNORED_METHODS_BY_LIB[name].includes(member)
+          )
+          .map((member) => {
+            const methodDocs = api[member].__docs__;
 
-          return {
-            name: `${name}.${member}`,
-            description: methodDocs?.text,
-            returnValue: methodDocs?.tags.return?.[0] ?? { type: 'undefined' },
-            params: methodDocs?.tags.param ?? [],
-            examples: methodDocs?.tags.examples ?? [],
-          };
-        }),
+            return {
+              name: `${name}.${member}`,
+              description: methodDocs?.text,
+              returnValue: methodDocs?.tags.return?.[0] ?? {
+                type: 'undefined',
+              },
+              params: methodDocs?.tags.param ?? [],
+              examples: methodDocs?.tags.examples ?? [],
+            };
+          }),
+      ],
     };
   }, [name]);
 };