Verify that all APIs are documented in unit test

Summary: When exposing new top-level APIs from `flipper-plugin`, they should be documented. Added a unit test to enforce this and added documentation for all missing APIs.

Reviewed By: passy

Differential Revision: D25421401

fbshipit-source-id: f5cafc1881de846c8a5dd86e5d094ebd27a66f2a

desktop/flipper-plugin/src/__tests__/api.node.tsx

@@ -7,6 +7,8 @@
  * @format
  */
 
+import {readFile} from 'fs';
+import {promisify} from 'util';
 import * as FlipperPluginModule from '../index';
 
 test('Correct top level API exposed', () => {
@@ -67,3 +69,21 @@ test('Correct top level API exposed', () => {
     ]
   `);
 });
+
+test('All APIs documented', async () => {
+  const docs = await promisify(readFile)(
+    __dirname + '/../../../../docs/extending/flipper-plugin.mdx',
+    'utf8',
+  );
+  Object.keys(FlipperPluginModule)
+    .filter(
+      (key) =>
+        !key.startsWith('_') && (FlipperPluginModule as any)[key] !== undefined,
+    )
+    .forEach((key) => {
+      // There should be a header with this identifier
+      if (!new RegExp(`# ${key}\\b`).test(docs)) {
+        fail(`Not documented: '${key}'`);
+      }
+    });
+});

docs/extending/flipper-plugin.mdx

@@ -386,6 +386,13 @@ interface Logger {
 }
 ```
 
+### useTrackedCallback
+
+Usage: `const eventHandler = useTrackedCallback("Interaction description", handlerFunction, deps)`
+
+Utility that wraps React's `useCallback` with tracking capabilities. 
+The API is similar, except that the first argument describes the interaction handled by the given event handler.
+See [Tracked](#tracked) for more info. 
 
 ## UI components
 
@@ -421,6 +428,19 @@ See `View > Flipper Style Guide` inside the Flipper application for more details
 
 ## Utilities
 
+### batch
+
+Usage: `batch(() => { /* state updates */ })`
+
+Low-level utility to batch state updates to reduce the amount of potential re-renders by React. 
+Wraps React's `unstable_batchedUpdates`. 
+Event handlers provided by React or `flipper-plugin` already apply `batch` automatically, so using this utility is only recommended when updating plugin state in an asynchronous process. 
+
+### produce
+
+A convenience re-export of `produce` from [Immer](https://immerjs.github.io/immer/docs/produce).
+The `update` method of the state atoms returned by `createState` automatically applies `produce` to its updater function. 
+
 ### renderReactRoot
 
 Usage: `renderReactRoot(handler: (unmount: () => void) => React.ReactElement)`
@@ -442,6 +462,16 @@ renderReactRoot((unmount) => (
 ));
 ```
 
+## sleep
+
+Usage: `await sleep(1000)`
+
+Creates a promise that automatically resolves after the specified amount of milliseconds.
+
+## styled
+
+A convenience re-export of `styled` from [emotion](https://emotion.sh/docs/styled).  
+
 ## TestUtils
 
 The object `TestUtils` as exposed from `flipper-plugin` exposes utilities to write unit tests for Sandy plugins.