add documentation for Fantom public APIs (facebook#50034)

Summary:
Pull Request resolved: facebook#50034

changelog: [internal]

add documentation for Fantom public APIs.

Reviewed By: rubennorte

Differential Revision: D71197744

fbshipit-source-id: dc7f97732eb6437bc0a33dec9fe2430e38c49e66

Author: sammy-SC

packages/react-native-fantom/src/index.js

@@ -129,17 +129,41 @@ const DEFAULT_TASK_PRIORITY = schedulerPriorityImmediate;
  * Schedules a task to run on the event loop.
  * If the work loop is running, it will be executed according to its priority.
  * Otherwise, it will wait in the queue until the work loop runs.
+ *
+ * @param task - The task to be scheduled.
+ *
+ * @example
+ * ```
+ * Fantom.scheduleTask(() => {
+ *   // Task to be run within React Native's scheduling.
+ * });
+ *
+ * // The task has not run yet.
+ *
+ * Fantom.runWorkLoop(); // Trigger work loop.
+ *
+ * // The task has been executed.
+ * ```
  */
 export function scheduleTask(task: () => void | Promise<void>) {
   nativeRuntimeScheduler.unstable_scheduleCallback(DEFAULT_TASK_PRIORITY, task);
 }
 
 let flushingQueue = false;
 
-/*
- * Runs a task on the event loop. To be used together with root.render.
- *
+/**
+ * Runs a task on the event loop.
  * React must run inside of event loop to ensure scheduling environment is closer to production.
+ *
+ * @param task - The task to run.
+ *
+ * @example
+ * ```
+ * const root = Fantom.createRoot();
+ * Fantom.runTask(() => {
+ *   root.render(<View />);
+ * });
+ * ```
  */
 export function runTask(task: () => void | Promise<void>) {
   if (flushingQueue) {
@@ -152,15 +176,32 @@ export function runTask(task: () => void | Promise<void>) {
   runWorkLoop();
 }
 
-/*
- * Simmulates running a task on the UI thread and forces side effect to drain the event queue, scheduling events to be dispatched to JavaScript.
+/**
+ * Simulates running a task on the UI thread and forces side effect to drain
+ * the event queue, scheduling events to be dispatched to JavaScript.
+ * To be used when enqueuing native events.
+ *
+ * @param task - The task to run on the UI thread.
+ *
+ * @example
+ * ```
+ * Fantom.runOnUIThread(() => {
+ *   Fantom.enqueueNativeEvent(element, 'focus');
+ * });
+ *
+ * // The effects of `focus` event are *not* yet observable.
+ *
+ * Fantom.runWorkLoop();
+ *
+ * // The effects of `focus` event are now observable.
+ * ```
  */
 export function runOnUIThread(task: () => void) {
   task();
   NativeFantom.flushEventQueue();
 }
 
-/*
+/**
  * Runs a side effect to drain the event queue and dispatches events to JavaScript.
  * Useful to flash out all tasks.
  */
@@ -171,6 +212,20 @@ export function flushAllNativeEvents() {
 
 /**
  * Runs the event loop until all tasks are executed.
+ * To be used with `Fantom.enqueueNativeEvent` and `Fantom.scheduleTask`.
+ *
+ * @example
+ * ```
+ * Fantom.scheduleTask(() => {
+ *   // Task to be run within React Native's scheduling.
+ * });
+ *
+ * // The task has not run yet.
+ *
+ * Fantom.runWorkLoop();
+ *
+ * // The task has been executed.
+ * ```
  */
 export function runWorkLoop(): void {
   if (flushingQueue) {
@@ -187,8 +242,23 @@ export function runWorkLoop(): void {
   }
 }
 
-// TODO: Add option to define surface props and pass it to startSurface
-// Surfacep rops: concurrentRoot, surfaceWidth, surfaceHeight, layoutDirection, pointScaleFactor.
+/**
+ * Create a Root that can render a React component tree.
+ *
+ * Accepts an optional RootConfig with the following optional options:
+ * @param devicePixelRatio - Numeric value, defaults to 3 (iPhone 14).
+ * @param viewportHeight - Numeric value, defaults to 844 (iPhone 14).
+ * @param viewportWidth - Numeric value, defaults to 390 (iPhone 14).
+ *
+ * @example
+ * ```
+ * const root = Fantom.createRoot({
+ *  viewportWidth: 200, // default is 390
+ *  viewportHeight: 600, // default is 844
+ *  devicePixelRatio: 2, // default is 3
+ * });
+ * ```
+ */
 export function createRoot(rootConfig?: RootConfig): Root {
   return new Root(rootConfig);
 }
@@ -198,7 +268,25 @@ export function createRoot(rootConfig?: RootConfig): Root {
  * It does not wait for it to be flushed in the UI thread or for it to be
  * processed by JS.
  *
- * For a higher level API, use `dispatchNativeEvent`.
+ * When you simply need to dispatch a native event and observe its effects, use `dispatchNativeEvent`.
+ *
+ * @param node - The node to which the event will be dispatched. You must make sure the event is appropriate for the provided node. For example, if sending a scroll event, you must make sure the node is of type <ScrollView />.
+ * @param type - The type of the event. e.g 'focus', 'blur', 'change', 'scroll', etc.
+ * @param payload - The data associated with the event. What is delivered as `event.nativeEvent` on a component.
+ * @param options - Object describing what priority the event is and whether it gets coalesced. For event priority, see `NativeEventCategory`.
+ *
+ * @example
+ * ```
+ * Fantom.runOnUIThread(() => {
+ *   Fantom.enqueueNativeEvent(element, 'focus');
+ * });
+ *
+ * // The effects of `focus` event are *not* yet observable.
+ *
+ * Fantom.runWorkLoop();
+ *
+ * // The effects of `focus` event are observable.
+ * ```
  */
 export function enqueueNativeEvent(
   node: ReactNativeElement,
@@ -216,6 +304,21 @@ export function enqueueNativeEvent(
   );
 }
 
+/**
+ * Dispatches a native event and makes sure its effects are observable after calling this method.
+ *
+ * @param node - The node to which the event will be dispatched. You must make sure the event is appropriate for the provided node. For example, if sending a scroll event, you must make sure the node is of type <ScrollView />.
+ * @param type - The type of the event. e.g 'focus', 'blur', 'change', 'scroll', etc.
+ * @param payload - The data associated with the event. What is delivered as `event.nativeEvent` on a component.
+ * @param options - Object describing what priority the event is and whether it gets coalesced. For event priority, see `NativeEventCategory`.
+ *
+ * @example
+ * ```
+ * Fantom.dispatchNativeEvent(element, 'focus');
+ *
+ * // The effects of `focus` are immediately observable.
+ * ```
+ */
 export function dispatchNativeEvent(
   node: ReactNativeElement,
   type: string,
@@ -235,6 +338,47 @@ export type ScrollEventOptions = {
   zoomScale?: number,
 };
 
+/**
+ * Enqueues an event to scroll a <ScrollView /> node to the given coordinates.
+ * It does not wait for it to be flushed in the UI thread or for it to be
+ * processed by JS.
+ *
+ * When you need to simply scroll a <ScrollView /> and observe effects immediately, use `Fantom.scrollTo`.
+ *
+ * @params node - A node to be scrolled. Must be of type <ScrollView />.
+ * @params options - Object describing the scroll position and zoom level. See `ScrollEventOptions` for more details.
+ *
+ * @example
+ * ```
+ * const root = Fantom.createRoot();
+ * let maybeScrollViewNode;
+ *
+ * Fantom.runTask(() => {
+ *   root.render(
+ *     <ScrollView
+ *       ref={node => {
+ *         maybeScrollViewNode = node;
+ *       }} />
+ *       <ScrollViewContent />
+ *     </ScrollView>,
+ *   );
+ * });
+ *
+ * const element = ensureInstance(maybeScrollViewNode, ReactNativeElement);
+ *
+ * Fantom.runOnUIThread(() => {
+ *   Fantom.enqueueScrollEvent(element, {
+ *     x: 20,
+ *     y: 10,
+ *  });
+ *
+ * // The changes from scroll event are *not* yet observable.
+ *
+ * Fantom.runWorkLoop();
+ *
+ * // The changes from scroll event are observable.
+ * ```
+ */
 export function enqueueScrollEvent(
   node: ReactNativeElement,
   options: ScrollEventOptions,
@@ -248,6 +392,9 @@ export function enqueueScrollEvent(
  * The call is immediately observable unlike `Fantom.enqueueScrollEvent` where the
  * event is queued and not processed.
  *
+ * @params node - A node to be scrolled. Must be of type <ScrollView />.
+ * @params options - Object describing the scroll position and zoom level. See `ScrollEventOptions` for more details.
+ *
  * @example
  * ```
  * const root = Fantom.createRoot();
@@ -282,6 +429,30 @@ export function scrollTo(
   runWorkLoop();
 }
 
+/**
+ * Enqueues modal size update for a given node.
+ * It does not wait for it to be processed and effects are not observable after calling this method.
+ * Can only be called on <Modal />.
+ *
+ * @params node - A node to have its size updated. Must be of type <Modal />.
+ * @params size - New size for the node. This would typically be screen size.
+ *
+ * @example
+ * ```
+ * Fantom.runOnUIThread(() => {
+ *   Fantom.enqueueModalSizeUpdate(modalElement, {
+ *     width: 100,
+ *     height: 100,
+ *   });
+ * });
+ *
+ * // The effects of `enqueueModalSizeUpdate` are *not* yet observable.
+ *
+ * Fantom.runWorkLoop();
+ *
+ * // The effects of `enqueueModalSizeUpdate` are yet observable.
+ * ```
+ */
 export function enqueueModalSizeUpdate(
   node: ReactNativeElement,
   size: {width: number, height: number},
@@ -372,6 +543,17 @@ if (typeof global.EventTarget === 'undefined') {
   );
 }
 
+/**
+ * Saves a heap snapshot after forcing garbage collection.
+ *
+ * The heapsnapshot is saved to the filename supplied as an argument.
+ * If a relative path is supplied, it will be saved relative to where you are invoking the tests.
+ *
+ * The supplied filename should end in .heapsnapshot, and it can be opened
+ * using the "Memory" pane in Chrome DevTools.
+ *
+ * @param filepath - File where JS memory heap will be saved.
+ */
 export function saveJSMemoryHeapSnapshot(filePath: string): void {
   if (getConstants().isRunningFromCI) {
     throw new Error('Unexpected call to `saveJSMemoryHeapSnapshot` from CI');