Summary docs

api-report/runtime-definitions.api.md

@@ -354,7 +354,7 @@ export interface ISummarizerNodeWithGC extends ISummarizerNode {
     updateUsedRoutes(usedRoutes: string[], gcTimestamp?: number): void;
 }
 
-// @public (undocumented)
+// @public
 export interface ISummaryStats {
     // (undocumented)
     blobNodeCount: number;
@@ -368,11 +368,9 @@ export interface ISummaryStats {
     unreferencedBlobSize: number;
 }
 
-// @public (undocumented)
+// @public
 export interface ISummaryTreeWithStats {
-    // (undocumented)
     stats: ISummaryStats;
-    // (undocumented)
     summary: ISummaryTree;
 }
 

common/lib/protocol-definitions/src/summary.ts

@@ -21,41 +21,88 @@ export interface ISummaryCommitter {
     date: string;
 }
 
+/**
+ *  Represents a node from the Summary Tree.
+ */
+// eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace SummaryType {
     export type Tree = 1;
     export type Blob = 2;
     export type Handle = 3;
     export type Attachment = 4;
 
-    export const Tree: Tree = 1 as const;
-    export const Blob: Blob = 2 as const;
-    export const Handle: Handle = 3 as const;
-    export const Attachment: Attachment = 4 as const;
+    /**
+     *  Represents a sub-tree in the summary.
+     */
+     export const Tree: Tree = 1 as const;
+
+     /**
+      * Represents a blob of data that is added to the summary.
+      * Such as the user data that is added to the DDS or metadata added by runtime
+      * such as data store / channel attributes.
+      */
+     export const Blob: Blob = 2 as const;
+
+     /**
+      * Path to a summary tree object from the last successful summary.
+      */
+     export const Handle: Handle = 3 as const;
+
+     /**
+      * Unique identifier to larger blobs uploaded outside of the summary.
+      * Ex. DDS has large images or video that will be uploaded by the BlobManager and
+      * receive an Id that can be used in the summary.
+      */
+     export const Attachment: Attachment = 4 as const;
 }
 export type SummaryType = SummaryType.Attachment | SummaryType.Blob | SummaryType.Handle | SummaryType.Tree;
 
 export type SummaryTypeNoHandle = SummaryType.Tree | SummaryType.Blob | SummaryType.Attachment;
 
+/**
+ * Path to a summary tree object from the last successful summary indicating the summary object hasn't
+ * changed since it was uploaded.
+ * To illustrate, if a DataStore did not change since last summary, the framework runtime will use a handle for the
+ * entire DataStore instead of re-sending the entire subtree. The same concept applies for a DDS.
+ * An example of handle would be: '/<DataStoreId>/<DDSId>'.
+ * Notice that handles are optimizations from the Fluid Framework Runtime and the DDS is not aware of the handles.
+ */
 export interface ISummaryHandle {
     type: SummaryType.Handle;
 
-    // No handles, all other SummaryType are Ok
+    /**
+     * Type of Summary Handle (SummaryType.Handle is not supported).
+     */
     handleType: SummaryTypeNoHandle;
 
-    // Stored handle reference
+    /**
+     * Unique path that identifies the stored handle reference.
+     */
     handle: string;
 }
 
+/**
+ * String or Binary data to be uploaded to the server as part of the document's Summary.
+ */
 export interface ISummaryBlob {
     type: SummaryType.Blob;
     content: string | Uint8Array;
 }
 
+/**
+ * Handle to blobs uploaded outside of the summary. Attachment Blobs are uploaded and downloaded separately via
+ * http requests and  are not included on the snapshot payload. The ISummaryAttachment are handles to these blobs.
+ * Additional information can be found here: https://github.com/microsoft/FluidFramework/issues/6374
+ */
 export interface ISummaryAttachment {
     type: SummaryType.Attachment;
     id: string;
 }
 
+/**
+ * Tree Node data structure with children that are nodes of SummaryObject type:
+ * Blob, Handle, Attachment or another Tree.
+ */
 export interface ISummaryTree {
     type: SummaryType.Tree;
 

packages/runtime/datastore-definitions/src/channel.ts

@@ -21,13 +21,19 @@ export interface IChannel extends IFluidLoadable {
 
     /**
      * Generates summary of the channel synchronously.
+     * @param fullTree - flag indicating whether the attempt should generate a full
+     * summary tree without any handles for unchanged subtrees.
+     * @param trackState - This tells whether we should track state from this summary.
      * @returns A tree representing the summary of the channel.
      */
     getAttachSummary(fullTree?: boolean, trackState?: boolean): ISummaryTreeWithStats;
 
     /**
      * Generates summary of the channel asynchronously.
      * This should not be called where the channel can be modified while summarization is in progress.
+     * @param fullTree - flag indicating whether the attempt should generate a full
+     * summary tree without any handles for unchanged subtrees.
+     * @param trackState - This tells whether we should track state from this summary.
      * @returns A tree representing the summary of the channel.
      */
     summarize(fullTree?: boolean, trackState?: boolean): Promise<ISummaryTreeWithStats>;

packages/runtime/runtime-definitions/src/summary.ts

@@ -16,6 +16,9 @@ import {
     IGarbageCollectionSummaryDetails,
 } from "./garbageCollection";
 
+/**
+ * Contains the aggregation data from a Tree/Subtree.
+ */
 export interface ISummaryStats {
     treeNodeCount: number;
     blobNodeCount: number;
@@ -24,8 +27,20 @@ export interface ISummaryStats {
     unreferencedBlobSize: number;
 }
 
+/**
+ *  The summarization methods are recursively invoked during the summary calculation and will
+ *  compose the Summary Tree. At the same time, each component that is taking part of the summarization
+ *  will populate the tree information aggregation for its subtree through the ISummaryStats interface.
+ *  Any component that implements IChannelContext, IFluidDataStoreChannel or extends SharedObject
+ *  will be taking part of the summarization process.
+ */
 export interface ISummaryTreeWithStats {
+    /** Represents an agreggation of node counts and blob sizes associated to the current summary information */
     stats: ISummaryStats;
+    /**
+     * Summary defines a recursive data structure that will be converted to a snapshot tree and uploaded
+     * to the backend.
+     */
     summary: ISummaryTree;
 }