chore(doc) improve documentation

Summary: Reformat the MemLab documentation, add more in-doc links to make it easy to navigate between different API documentations. Differential Revision: D53392357 fbshipit-source-id: 21c0f218dd6afa99519a46b4bce94dc2d820e7ee
facebook · Feb 7, 2024 · bb1a3b6 · bb1a3b6
1 parent 6de17a7
commit bb1a3b6
Show file tree

Hide file tree

Showing 12 changed files with 301 additions and 229 deletions.
diff --git a/packages/core/src/lib/Types.ts b/packages/core/src/lib/Types.ts
@@ -404,13 +404,14 @@ export interface ILeakFilter {
    * be used to initialize some data stores or any one-off
    * preprocessings.
    *
-   * * **Parameters**:
-   *   * snapshot: `IHeapSnapshot` | the final heap snapshot taken after
-   *     all browser interactions are done.
-   *     Check out {@link IHeapSnapshot} for more APIs that queries the heap snapshot.
-   *   * leakedNodeIds: `Set<number>` | the set of ids of all JS heap objects
-   *     allocated by the `action` call but not released after the `back` call
-   *     in browser.
+   * * * **Parameters**:
+   *   * `snapshot`: <code>{@link IHeapSnapshot}</code> | the final heap
+   *      snapshot taken after all browser interactions are done.
+   *      Check out {@link IHeapSnapshot} for more APIs that queries the
+   *      heap snapshot.
+   *   * `leakedNodeIds`: `Set<number>` | the set of ids of all JS heap objects
+   *      allocated by the `action` call but not released after the `back` call
+   *      in browser.
    *
    * * **Examples**:
    * ```javascript
@@ -441,13 +442,16 @@ export interface ILeakFilter {
    * memory leaks.
    *
    * * **Parameters**:
-   *   * node: `IHeapNode` | one of the heap object allocated but not released.
-   *   * snapshot: `IHeapSnapshot` | the final heap snapshot taken after
-   *     all browser interactions are done.
-   *     Check out {@link IHeapSnapshot} for more APIs that queries the heap snapshot.
-   *   * leakedNodeIds: `Set<number>` | the set of ids of all JS heap objects
-   *     allocated by the `action` call but not released after the `back` call
-   *     in browser.
+   *   * `node`: <code>{@link IHeapNode}</code> | the heap object
+   *      allocated but not released. This filter callback will be applied
+   *      to each node allocated but not released in the heap snapshot.
+   *   * `snapshot`: <code>{@link IHeapSnapshot}</code> | the final heap
+   *      snapshot taken after all browser interactions are done.
+   *      Check out {@link IHeapSnapshot} for more APIs that queries the
+   *      heap snapshot.
+   *   * `leakedNodeIds`: `Set<number>` | the set of ids of all JS heap objects
+   *      allocated by the `action` call but not released after the `back` call
+   *      in browser.
    *
    * * **Returns**: the boolean value indicating whether the given node in
    *   the snapshot should be considered as leaked.
@@ -482,13 +486,16 @@ export interface ILeakFilter {
    * For concrete examples, check out {@link leakFilter}.
    *
    * * **Parameters**:
-   *   * edge - the reference (edge) that is considered
-   *     for calcualting the retainer trace
-   *   * snapshot - the snapshot of target interaction
-   *   * isReferenceUsedByDefault - MemLab has its own default logic for
-   *     whether a reference should be considered as part of the retainer trace,
-   *     if this parameter is true, it means MemLab will consider this reference
-   *     when calculating the retainer trace.
+   *   * `edge` : <code>{@link IHeapEdge}</code> | the reference (edge)
+   *      that is considered for calcualting the retainer trace
+   *   * `snapshot`: <code>{@link IHeapSnapshot}</code> | the final heap
+   *      snapshot taken after all browser interactions are done.
+   *      Check out {@link IHeapSnapshot} for more APIs that queries the
+   *      heap snapshot.
+   *   * `isReferenceUsedByDefault`: `boolean` | MemLab has its own default
+   *      logic for whether a reference should be considered as part of the
+   *      retainer trace, if this parameter is true, it means MemLab will
+   *      consider this reference when calculating the retainer trace.
    *
    * * **Returns**: the value indicating whether the given reference should be
    * considered when calculating the retainer trace. Note that when this
@@ -580,7 +587,8 @@ export type LeakFilterCallback = (
  *
  * @param edge - the reference (edge) that is considered
  * for calcualting the retainer trace
- * @param snapshot - the snapshot of target interaction
+ * @param snapshot - the final snapshot taken after all browser
+ * interactions are done.
  * @param isReferenceUsedByDefault - MemLab has its own default logic for
  * whether a reference should be filtered (included), if this parameter is true,
  * it means MemLab will consider this reference for inclusion
@@ -699,7 +707,8 @@ export interface IScenario {
    * the HTTP headers or to prepare data before loading the web page.
    *
    * * **Parameters**:
-   *   * page: `Page` | the puppeteer [`Page`](https://pptr.dev/api/puppeteer.page)
+   *   * `page`: <code>{@link Page}</code> | the puppeteer
+   *     [`Page`](https://pptr.dev/api/puppeteer.page)
    *     object, which provides APIs to interact with the web browser. To import
    *     this type, check out {@link Page}.
    *
@@ -747,7 +756,8 @@ export interface IScenario {
    * or to prepare data before the {@link action} call.
    *
    * * **Parameters**:
-   *   * page: `Page` | the puppeteer [`Page`](https://pptr.dev/api/puppeteer.page)
+   *   * `page`: <code>{@link Page}</code> | the puppeteer
+   *     [`Page`](https://pptr.dev/api/puppeteer.page)
    *     object, which provides APIs to interact with the web browser. To import
    *     this type, check out {@link Page}.
    *
@@ -777,7 +787,8 @@ export interface IScenario {
    * from the `action` callback will be candidates for memory leak filtering.
    *
    * * **Parameters**:
-   *   * page: `Page` | the puppeteer [`Page`](https://pptr.dev/api/puppeteer.page)
+   *   * `page`: <code>{@link Page}</code> | the puppeteer
+   *     [`Page`](https://pptr.dev/api/puppeteer.page)
    *     object, which provides APIs to interact with the web browser. To import
    *     this type, check out {@link Page}.
    *
@@ -821,7 +832,8 @@ export interface IScenario {
    * back/revert the `action` callback. Think of it as an undo action.
    *
    * * **Parameters**:
-   *   * page: `Page` | the puppeteer [`Page`](https://pptr.dev/api/puppeteer.page)
+   *   * `page`: <code>{@link Page}</code> | the puppeteer
+   *     [`Page`](https://pptr.dev/api/puppeteer.page)
    *     object, which provides APIs to interact with the web browser. To import
    *     this type, check out {@link Page}.
    *
@@ -842,7 +854,11 @@ export interface IScenario {
    */
   back?: InteractionsCallback;
   /**
-   * Specifies how many **extra** `action` and `back` actions performed by memlab.
+   * Specifies how many **extra** `action` and `back` actions performed
+   * by memlab.
+   *
+   * * **Returns**: a number value specifies the number of extra actions.
+   *
    * * **Examples**:
    * ```typescript
    * module.exports = {
@@ -865,13 +881,16 @@ export interface IScenario {
    * connections for at least 500ms.
    *
    * * **Parameters**:
-   *   * page: `Page` | the puppeteer [`Page`](https://pptr.dev/api/puppeteer.page)
+   *   * `page`: <code>{@link Page}</code> | the puppeteer
+   *     [`Page`](https://pptr.dev/api/puppeteer.page)
    *     object, which provides APIs to interact with the web browser. To import
    *     this type, check out {@link Page}.
+   *
    * * **Returns**: a boolean value, if it returns `true`, memlab will consider
    *   the navigation completes, if it returns `false`, memlab will keep calling
    *   this callback until it returns `true`. This is an async callback, you can
    *   also `await` and returns `true` until some async logic is resolved.
+   *
    * * **Examples**:
    * ```typescript
    * module.exports = {
@@ -899,12 +918,13 @@ export interface IScenario {
    * preprocessings.
    *
    * * **Parameters**:
-   *   * snapshot: `IHeapSnapshot` | the final heap snapshot taken after
-   *     all browser interactions are done.
-   *     Check out {@link IHeapSnapshot} for more APIs that queries the heap snapshot.
-   *   * leakedNodeIds: `Set<number>` | the set of ids of all JS heap objects
-   *     allocated by the `action` call but not released after the `back` call
-   *     in browser.
+   *   * `snapshot`: <code>{@link IHeapSnapshot}</code> | the final heap
+   *      snapshot taken after all browser interactions are done.
+   *      Check out {@link IHeapSnapshot} for more APIs that queries the
+   *      heap snapshot.
+   *   * `leakedNodeIds`: `Set<number>` | the set of ids of all JS heap objects
+   *      allocated by the `action` call but not released after the `back` call
+   *      in browser.
    *
    * * **Examples**:
    * ```typescript
@@ -935,13 +955,16 @@ export interface IScenario {
    * memory leaks.
    *
    * * **Parameters**:
-   *   * node: `IHeapNode` | one of the heap object allocated but not released.
-   *   * snapshot: `IHeapSnapshot` | the final heap snapshot taken after
-   *     all browser interactions are done.
-   *     Check out {@link IHeapSnapshot} for more APIs that queries the heap snapshot.
-   *   * leakedNodeIds: `Set<number>` | the set of ids of all JS heap objects
-   *     allocated by the `action` call but not released after the `back` call
-   *     in browser.
+   *   * `node`: <code>{@link IHeapNode}</code> | the heap object
+   *      allocated but not released. This filter callback will be applied
+   *      to each node allocated but not released in the heap snapshot.
+   *   * `snapshot`: <code>{@link IHeapSnapshot}</code> | the final heap
+   *      snapshot taken after all browser interactions are done.
+   *      Check out {@link IHeapSnapshot} for more APIs that queries the
+   *      heap snapshot.
+   *   * `leakedNodeIds`: `Set<number>` | the set of ids of all JS heap objects
+   *      allocated by the `action` call but not released after the `back` call
+   *      in browser.
    *
    * * **Returns**: the boolean value indicating whether the given node in
    *   the snapshot should be considered as leaked.
@@ -969,13 +992,16 @@ export interface IScenario {
    * For concrete examples, check out {@link leakFilter}.
    *
    * * **Parameters**:
-   *   * edge - the reference (edge) that is considered
-   *     for calcualting the retainer trace
-   *   * snapshot - the snapshot of target interaction
-   *   * isReferenceUsedByDefault - MemLab has its own default logic for
-   *     whether a reference should be considered as part of the retainer trace,
-   *     if this parameter is true, it means MemLab will consider this reference
-   *     when calculating the retainer trace.
+   *   * `edge` : <code>{@link IHeapEdge}</code> | the reference (edge)
+   *      that is considered for calcualting the retainer trace
+   *   * `snapshot`: <code>{@link IHeapSnapshot}</code> | the heap snapshot
+   *      taken after all browser interactions are done.
+   *      Check out {@link IHeapSnapshot} for more APIs that queries the
+   *      heap snapshot.
+   *   * `isReferenceUsedByDefault`: `boolean` | MemLab has its own default
+   *      logic for whether a reference should be considered as part of the
+   *      retainer trace, if this parameter is true, it means MemLab will
+   *      consider this reference when calculating the retainer trace.
    *
    * * **Returns**: the value indicating whether the given reference should be
    * considered when calculating the retainer trace. Note that when this
@@ -1557,8 +1583,11 @@ export interface IHeapLocation {
   /**
    * convert to a concise readable string output
    * (like calling `JSON.stringify(node, ...args)`).
-   * Note: calling `JSON.stringify(node, ...args)` will not work
-   * since the string is too large and not readable.
+   *
+   * Note: Please be aware that using `JSON.stringify(node, ...args)` is
+   * not recommended as it will generate a JSON representation of the host
+   * object that is too large to be easily readable due to its connections
+   * to other parts of the data structures within the heap snapshot.
    *
    * This API does not completely serialize all the information
    * captured by the hosting object.
@@ -1641,8 +1670,11 @@ export interface IHeapEdge extends IHeapEdgeBasic {
   /**
    * convert to a concise readable string output
    * (like calling `JSON.stringify(node, ...args)`).
-   * Note: calling `JSON.stringify(node, ...args)` will not work
-   * since the string is too large and not readable.
+   *
+   * Note: Please be aware that using `JSON.stringify(node, ...args)` is
+   * not recommended as it will generate a JSON representation of the host
+   * object that is too large to be easily readable due to its connections
+   * to other parts of the data structures within the heap snapshot.
    *
    * This API does not completely serialize all the information
    * captured by the hosting object.
@@ -1863,8 +1895,11 @@ export interface IHeapNode extends IHeapNodeBasic {
   /**
    * convert to a concise readable string output
    * (like calling `JSON.stringify(node, ...args)`).
-   * Note: calling `JSON.stringify(node, ...args)` will not work
-   * since the string is too large and not readable.
+   *
+   * Note: Please be aware that using `JSON.stringify(node, ...args)` is
+   * not recommended as it will generate a JSON representation of the host
+   * object that is too large to be easily readable due to its connections
+   * to other parts of the data structures within the heap snapshot.
    *
    * This API does not completely serialize all the information
    * captured by the hosting object.

diff --git a/website/docs/api/interfaces/core_src.IBrowserInfo.md b/website/docs/api/interfaces/core_src.IBrowserInfo.md
@@ -16,7 +16,7 @@ through [RunMetaInfo](../modules/core_src.md#runmetainfo).
 browser version
 
  * **Source**:
-    * core/src/lib/Types.ts:1194
+    * core/src/lib/Types.ts:1220
 
 ___
 
@@ -25,7 +25,7 @@ ___
 all web console output
 
  * **Source**:
-    * core/src/lib/Types.ts:1202
+    * core/src/lib/Types.ts:1228
 
 ___
 
@@ -34,4 +34,4 @@ ___
 configuration for puppeteer
 
  * **Source**:
-    * core/src/lib/Types.ts:1198
+    * core/src/lib/Types.ts:1224
diff --git a/website/docs/api/interfaces/core_src.IHeapEdge.md b/website/docs/api/interfaces/core_src.IHeapEdge.md
@@ -45,7 +45,7 @@ import {getFullHeapFromFile} from '@memlab/heap-analysis';
 index of this JS reference inside the `edge.snapshot.edges` pseudo array
 
  * **Source**:
-    * core/src/lib/Types.ts:1619
+    * core/src/lib/Types.ts:1648
 
 ___
 
@@ -55,7 +55,7 @@ returns an [IHeapNode](core_src.IHeapNode.md) instance representing the hosting
 JS heap object where this reference starts
 
  * **Source**:
-    * core/src/lib/Types.ts:1640
+    * core/src/lib/Types.ts:1669
 
 ___
 
@@ -67,7 +67,7 @@ otherwise this is a reference with a string name (`edge.name_or_index`
 will return a string)
 
  * **Source**:
-    * core/src/lib/Types.ts:1626
+    * core/src/lib/Types.ts:1655
 
 ___
 
@@ -77,7 +77,7 @@ name of the JS reference. If this is a reference to an array element
 or internal table element, it is an numeric index
 
  * **Source**:
-    * core/src/lib/Types.ts:1575
+    * core/src/lib/Types.ts:1604
 
 ___
 
@@ -86,7 +86,7 @@ ___
 get the [IHeapSnapshot](core_src.IHeapSnapshot.md) containing this JS reference
 
  * **Source**:
-    * core/src/lib/Types.ts:1615
+    * core/src/lib/Types.ts:1644
 
 ___
 
@@ -96,7 +96,7 @@ returns an [IHeapNode](core_src.IHeapNode.md) instance representing the JS heap
 pointed to by this reference
 
  * **Source**:
-    * core/src/lib/Types.ts:1635
+    * core/src/lib/Types.ts:1664
 
 ___
 
@@ -105,7 +105,7 @@ ___
 the index of the JS heap object pointed to by this reference
 
  * **Source**:
-    * core/src/lib/Types.ts:1630
+    * core/src/lib/Types.ts:1659
 
 ___
 
@@ -115,16 +115,19 @@ type of the JS reference, all types:
 `context`, `element`, `property`, `internal`, `hidden`, `shortcut`, `weak`
 
  * **Source**:
-    * core/src/lib/Types.ts:1580
+    * core/src/lib/Types.ts:1609
 
 ## Methods
 
 ### <a id="tojsonstring"></a>**toJSONString**(...`args`)
 
 convert to a concise readable string output
 (like calling `JSON.stringify(node, ...args)`).
-Note: calling `JSON.stringify(node, ...args)` will not work
-since the string is too large and not readable.
+
+Note: Please be aware that using `JSON.stringify(node, ...args)` is
+not recommended as it will generate a JSON representation of the host
+object that is too large to be easily readable due to its connections
+to other parts of the data structures within the heap snapshot.
 
 This API does not completely serialize all the information
 captured by the hosting object.
@@ -133,4 +136,4 @@ captured by the hosting object.
     * `...args`: `any`[]
  * **Returns**: `string`
  * **Source**:
-    * core/src/lib/Types.ts:1650
+    * core/src/lib/Types.ts:1682