docs(client): missing comments and @internal use fixes

packages/framework/fluid-static/src/types.ts

@@ -121,7 +121,7 @@ interface IProvideStaticEntryPoint {
 }
 
 /**
- * @internal
+ * This is the internal entry point fluid-static creates.
  */
 export interface IStaticEntryPoint extends IProvideStaticEntryPoint {
 	readonly rootDataObject: IRootDataObject;

packages/framework/presence/src/broadcastControls.ts

@@ -89,7 +89,8 @@ class ForcedRefreshControl
 }
 
 /**
- * @internal
+ * Implements {@link BroadcastControls} for States Managers
+ * where returning `undefined` settings are allowed.
  */
 export class OptionalBroadcastControl
 	extends ForcedRefreshControl
@@ -109,8 +110,6 @@ export class OptionalBroadcastControl
  *
  * If {@link BroadcastControls.allowableUpdateLatencyMs | allowableUpdateLatencyMs}
  * is set to `undefined`, the default will be restored.
- *
- * @internal
  */
 export class RequiredBroadcastControl
 	extends ForcedRefreshControl

packages/framework/presence/src/datastoreSupport.ts

@@ -3,6 +3,11 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * Collection of minimal (slim) helpers to support DataObject creation
+ * for temporary {@link ExperimentalPresenceManager}
+ */
+
 import type {
 	FluidObject,
 	IFluidLoadable,
@@ -47,7 +52,7 @@ class BasicFluidDataStoreRuntime extends FluidDataStoreRuntime {
 }
 
 /**
- * @internal
+ * Factory for creating a {@link BasicFluidDataStoreRuntime}
  */
 export class BasicDataStoreFactory<Type extends string> implements IFluidDataStoreFactory {
 	public get IFluidDataStoreFactory(): IFluidDataStoreFactory {
@@ -82,7 +87,7 @@ export class BasicDataStoreFactory<Type extends string> implements IFluidDataSto
 }
 
 /**
- * @internal
+ * Helper to build a DataObject handling the {@link FluidObject} and {@link IFluidLoadable} requirements.
  */
 export abstract class LoadableFluidObject implements FluidObject, IFluidLoadable {
 	public constructor(protected readonly runtime: FluidDataStoreRuntime) {}

packages/framework/presence/src/internalTypes.ts

@@ -15,19 +15,20 @@ import type {
 
 /**
  * Presence {@link ContainerExtension} version of {@link @fluidframework/container-runtime-definitions#ExtensionRuntimeProperties}
- * @internal
  */
 export interface ExtensionRuntimeProperties {
 	SignalMessages: SignalMessages;
 }
 /**
  * Presence specific ExtensionHost
- * @internal
  */
 export type ExtensionHost = ContainerExtensionHost<ExtensionRuntimeProperties>;
 
 /**
- * @internal
+ * Basic structure of set of {@link Attendee} records within Presence datastore
+ *
+ * @remarks
+ * This is commonly exists per named state in State Managers.
  */
 export interface ClientRecord<TValue extends InternalTypes.ValueDirectoryOrState<unknown>> {
 	// Caution: any particular item may or may not exist
@@ -42,8 +43,6 @@ export interface ClientRecord<TValue extends InternalTypes.ValueDirectoryOrState
  *
  * @privateRemarks
  * Replace with non-DataStore based interface.
- *
- * @internal
  */
 export type IEphemeralRuntime = Omit<ExtensionHost, "logger" | "submitAddressedSignal"> &
 	// Apart from tests, there is always a logger. So this could be promoted to required.
@@ -60,7 +59,10 @@ export type IEphemeralRuntime = Omit<ExtensionHost, "logger" | "submitAddressedS
 	};
 
 /**
- * @internal
+ * Contract for State Managers as used by a States Workspace (`PresenceStatesImpl`)
+ *
+ * @remarks
+ * See uses of `unbrandIVM`.
  */
 export interface ValueManager<
 	TValue,
@@ -73,6 +75,6 @@ export interface ValueManager<
 }
 
 /**
- * @internal
+ * A function to be called at the end of an update frame
  */
 export type PostUpdateAction = () => void;

packages/framework/presence/src/internalUtils.ts

@@ -29,8 +29,6 @@ type RequiredAndNotUndefined<T> = {
  * The is a defect in this utility when a string index appears in the object.
  * In such a case, the only result is `[string, T]`, where `T` is the type
  * of the string index entry.
- *
- * @internal
  */
 export const objectEntries = Object.entries as <const T>(o: T) => KeyValuePairs<T>;
 
@@ -41,17 +39,13 @@ export const objectEntries = Object.entries as <const T>(o: T) => KeyValuePairs<
  * Given `T` should not contain `undefined` values. If it does, use
  * {@link objectEntries} instead. Without `undefined` values, this
  * typing provides best handling of objects with optional properties.
- *
- * @internal
  */
 export const objectEntriesWithoutUndefined = Object.entries as <const T>(
 	o: T,
 ) => KeyValuePairs<RequiredAndNotUndefined<T>>;
 
 /**
  * Object.keys retyped to preserve known keys and their types.
- *
- * @internal
  */
 export const objectKeys = Object.keys as <const T>(
 	o: T,

packages/framework/presence/src/presence.ts

@@ -109,8 +109,6 @@ export interface Attendee<SpecificAttendeeId extends AttendeeId = AttendeeId> {
 /**
  * Utility type limiting to a specific attendee. (A attendee with
  * a specific session ID - not just any session ID.)
- *
- * @internal
  */
 export type SpecificAttendee<SpecificAttendeeId extends AttendeeId> =
 	string extends SpecificAttendeeId ? never : Attendee<SpecificAttendeeId>;

packages/framework/presence/src/presenceDatastoreManager.ts

@@ -73,7 +73,7 @@ function isPresenceMessage(
 }
 
 /**
- * @internal
+ * High-level contract for manager of singleton Presence datastore
  */
 export interface PresenceDatastoreManager {
 	joinSession(clientId: ClientConnectionId): void;

packages/framework/presence/src/presenceManager.ts

@@ -40,8 +40,6 @@ import type {
 
 /**
  * Portion of the container extension requirements ({@link ContainerExtension}) that are delegated to presence manager.
- *
- * @internal
  */
 export type PresenceExtensionInterface = Required<
 	Pick<ContainerExtension<ExtensionRuntimeProperties>, "processSignal">
@@ -185,8 +183,6 @@ function setupSubComponents(
 
 /**
  * Instantiates Presence Manager
- *
- * @internal
  */
 export function createPresenceManager(
 	runtime: IEphemeralRuntime,

packages/framework/presence/src/presenceStates.ts

@@ -30,8 +30,6 @@ import { unbrandIVM } from "./valueManager.js";
  * If the `Part` is an optional property, undefined will be included in the
  * result. Applying `Required` to the return type prior to extracting `Part`
  * does not work as expected. Use Exclude\<, undefined\> can be used as needed.
- *
- * @internal
  */
 export type MapSchemaElement<
 	TSchema extends StatesWorkspaceSchema,
@@ -40,9 +38,13 @@ export type MapSchemaElement<
 > = ReturnType<TSchema[Keys]>[Part];
 
 /**
- * @internal
+ * Miscellaneous options for local state updates
  */
 export interface RuntimeLocalUpdateOptions {
+	/**
+	 * The maximum time in milliseconds that this update is allowed to be
+	 * delayed before it must be sent to the service.
+	 */
 	allowableUpdateLatencyMs: number;
 
 	/**
@@ -52,7 +54,7 @@ export interface RuntimeLocalUpdateOptions {
 }
 
 /**
- * @internal
+ * Contract for `PresenceDatastoreManager` as required by States Workspaces ({@link PresenceStatesImpl}).
  */
 export interface PresenceRuntime {
 	readonly presence: Presence;
@@ -84,8 +86,6 @@ type MapEntries<TSchema extends StatesWorkspaceSchema> = PresenceSubSchemaFromWo
  *
  * This generic aspect makes some typing difficult. The loose typing is not broadcast to the
  * consumers that are expected to maintain their schema over multiple versions of clients.
- *
- * @internal
  */
 export interface ValueElementMap<_TSchema extends StatesWorkspaceSchema> {
 	[key: string]: ClientRecord<InternalTypes.ValueDirectoryOrState<unknown>>;
@@ -113,7 +113,7 @@ export interface ValueElementMap<_TSchema extends StatesWorkspaceSchema> {
 // }
 
 /**
- * @internal
+ * Data content of a datastore entry in update messages
  */
 export type ClientUpdateEntry = InternalTypes.ValueDirectoryOrState<unknown> & {
 	ignoreUnmonitored?: true;
@@ -126,7 +126,7 @@ interface ValueUpdateRecord {
 }
 
 /**
- * @internal
+ * Contract for Workspaces as required by `PresenceDatastoreManager`
  */
 export interface PresenceStatesInternal {
 	ensureContent<TSchemaAdditional extends StatesWorkspaceSchema>(
@@ -154,8 +154,6 @@ function isValueDirectory<
 
 /**
  * Merge a value directory.
- *
- * @internal
  */
 export function mergeValueDirectory<
 	T,
@@ -208,8 +206,6 @@ export function mergeValueDirectory<
  * @remarks
  * In the case of ignored unmonitored data, the client entries are not stored,
  * though the value keys will be populated and often remain empty.
- *
- * @internal
  */
 export function mergeUntrackedDatastore(
 	key: string,

packages/framework/presence/src/protocol.ts

@@ -14,14 +14,14 @@ import type { ClientUpdateEntry } from "./presenceStates.js";
 import type { SystemWorkspaceDatastore } from "./systemWorkspace.js";
 
 /**
- * @internal
+ * Datastore that contains system workspace data
  */
 export interface SystemDatastore {
 	"system:presence": SystemWorkspaceDatastore;
 }
 
 /**
- * @internal
+ * General datastore (and message) structure.
  */
 export interface GeneralDatastoreMessageContent {
 	[WorkspaceAddress: string]: {
@@ -34,7 +34,7 @@ export interface GeneralDatastoreMessageContent {
 type DatastoreMessageContent = GeneralDatastoreMessageContent & SystemDatastore;
 
 /**
- * @internal
+ * Datastore update message type.
  */
 export const datastoreUpdateMessageType = "Pres:DatastoreUpdate";
 interface DatastoreUpdateMessage {
@@ -48,18 +48,18 @@ interface DatastoreUpdateMessage {
 }
 
 /**
- * @internal
+ * Outbound datastore update message
  */
 export type OutboundDatastoreUpdateMessage = OutboundExtensionMessage<DatastoreUpdateMessage>;
 
 /**
- * @internal
+ * Inbound and verified datastore update message
  */
 export type InboundDatastoreUpdateMessage =
 	VerifiedInboundExtensionMessage<DatastoreUpdateMessage>;
 
 /**
- * @internal
+ * Client join message type.
  */
 export const joinMessageType = "Pres:ClientJoin";
 interface ClientJoinMessage {
@@ -73,16 +73,16 @@ interface ClientJoinMessage {
 }
 
 /**
- * @internal
+ * Outbound client join message
  */
 export type OutboundClientJoinMessage = OutboundExtensionMessage<ClientJoinMessage>;
 
 /**
- * @internal
+ * Inbound and verified client join message
  */
 export type InboundClientJoinMessage = VerifiedInboundExtensionMessage<ClientJoinMessage>;
 
 /**
- * @internal
+ * Messages structures that can be sent and received as understood in the presence protocol
  */
 export type SignalMessages = ClientJoinMessage | DatastoreUpdateMessage;

packages/framework/presence/src/stateDatastore.ts

@@ -16,9 +16,6 @@ import type {
 // 	TValue extends InternalTypes.ValueDirectoryOrState<any> = InternalTypes.ValueDirectoryOrState<unknown>,
 // > = TValue extends InternalTypes.ValueDirectoryOrState<infer T> ? InternalTypes.ValueDirectoryOrState<T> : never;
 
-// /**
-//  * @internal
-//  */
 // export interface StateDatastoreSchema {
 // 	// This type is not precise. It may
 // 	// need to be replaced with StatesWorkspace schema pattern
@@ -28,9 +25,14 @@ import type {
 // }
 
 /**
- * @internal
+ * Miscellaneous options for local state updates
  */
 export interface LocalStateUpdateOptions {
+	/**
+	 * When defined, this is the maximum time in milliseconds that this
+	 * update is allowed to be delayed before it must be sent to service.
+	 * When `undefined`, the callee may determine maximum delay.
+	 */
 	allowableUpdateLatencyMs: number | undefined;
 
 	/**
@@ -40,7 +42,8 @@ export interface LocalStateUpdateOptions {
 }
 
 /**
- * @internal
+ * Contract for States Workspace to support State Manager access to
+ * datastore and general internal presence knowledge.
  */
 export interface StateDatastore<
 	TKey extends string,
@@ -64,8 +67,6 @@ export interface StateDatastore<
 
 /**
  * Helper to get a handle from a datastore.
- *
- * @internal
  */
 export function handleFromDatastore<
 	// Constraining TSchema would be great, but it seems nested types (at least with undefined) cause trouble.
@@ -84,8 +85,6 @@ export function handleFromDatastore<
 
 /**
  * Helper to get the datastore back from its handle.
- *
- * @internal
  */
 export function datastoreFromHandle<
 	TKey extends string,