From 74e28ebfa09234c96dcab4a0cbb4a6c21449628c Mon Sep 17 00:00:00 2001
From: Jason Hartman <jasonha@microsoft.com>
Date: Thu, 26 Dec 2024 15:37:14 -0800
Subject: [PATCH] docs: update/correct comments for submitSignalFn including
 notes about how change might be possible (removing `@alpha` is insufficient)

---
 .../common/container-definitions/src/runtime.ts     | 13 ++++++++++---
 packages/loader/container-loader/src/container.ts   |  5 ++++-
 .../loader/container-loader/src/containerContext.ts |  7 +++++--
 .../container-runtime/src/containerRuntime.ts       |  2 +-
 4 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/packages/common/container-definitions/src/runtime.ts b/packages/common/container-definitions/src/runtime.ts
index ad034f7c4d19..c5ee9f9ace85 100644
--- a/packages/common/container-definitions/src/runtime.ts
+++ b/packages/common/container-definitions/src/runtime.ts
@@ -131,11 +131,15 @@ export interface IBatchMessage {
  * loader layer.
  * It gets passed into the {@link (IRuntimeFactory:interface).instantiateRuntime} call.
  *
- * @privateremarks
+ * @privateRemarks
  * Only include members on this interface if you intend them to be consumed/called from the runtime layer.
  *
- * TODO: once `@alpha` tag is removed, `unknown` should be removed from submitSignalFn.
- * See {@link https://dev.azure.com/fluidframework/internal/_workitems/edit/7462}
+ * TODO: once `@internal` or `@system`, `submitSignalFn`'s `contents` `unknown` type should be replaced with
+ * {@link @fluidframework/core-interfaces#ISignalEnvelope}.
+ * See {@link https://dev.azure.com/fluidframework/internal/_workitems/edit/7462}.
+ *
+ * To get `IContainerContext` internal, likely externally exposed uses will need
+ * to be replaced with a branded or otherwise erased type.
  *
  * @legacy
  * @alpha
@@ -173,6 +177,9 @@ export interface IContainerContext {
 		summaryOp: ISummaryContent,
 		referenceSequenceNumber?: number,
 	) => number;
+	/**
+	 * @param content - Expected to be of type {@link @fluidframework/core-interfaces/internal#ISignalEnvelope}.
+	 */
 	readonly submitSignalFn: (contents: unknown, targetClientId?: string) => void;
 	readonly disposeFn?: (error?: ICriticalContainerError) => void;
 	readonly closeFn: (error?: ICriticalContainerError) => void;
diff --git a/packages/loader/container-loader/src/container.ts b/packages/loader/container-loader/src/container.ts
index 35b747f10a20..0b0be542d480 100644
--- a/packages/loader/container-loader/src/container.ts
+++ b/packages/loader/container-loader/src/container.ts
@@ -2378,7 +2378,10 @@ export class Container
 		this.emit("op", message);
 	}
 
-	// unknown should be removed once `@alpha` tag is removed from IContainerContext
+	/**
+	 * `unknown` should be removed once `IContainerContext` is `@internal` or `@system`.
+	 * @see {@link https://dev.azure.com/fluidframework/internal/_workitems/edit/7462}
+	 */
 	private submitSignal(content: unknown | ISignalEnvelope, targetClientId?: string): void {
 		this._deltaManager.submitSignal(JSON.stringify(content), targetClientId);
 	}
diff --git a/packages/loader/container-loader/src/containerContext.ts b/packages/loader/container-loader/src/containerContext.ts
index 9fa5fa86ee32..211f32737f8f 100644
--- a/packages/loader/container-loader/src/containerContext.ts
+++ b/packages/loader/container-loader/src/containerContext.ts
@@ -91,9 +91,12 @@ export class ContainerContext implements IContainerContext {
 		) => number,
 
 		/**
-		 * `unknown` should be removed once `@alpha` tag is removed from IContainerContext
+		 * `unknown` should be removed once `IContainerContext` is `@internal` or `@system`.
 		 * @see {@link https://dev.azure.com/fluidframework/internal/_workitems/edit/7462}
-		 * Any changes to submitSignalFn `content` should be checked internally by temporarily changing IContainerContext and removing all `unknown`s
+		 *
+		 * @privateRemarks
+		 * Any changes to submitSignalFn `content` should be checked internally by temporarily
+		 * changing `IContainerContext` (replacing/removing all `unknown`s).
 		 */
 		public readonly submitSignalFn: (
 			content: unknown | ISignalEnvelope,
diff --git a/packages/runtime/container-runtime/src/containerRuntime.ts b/packages/runtime/container-runtime/src/containerRuntime.ts
index 2f1a413b5782..ed985414b9d2 100644
--- a/packages/runtime/container-runtime/src/containerRuntime.ts
+++ b/packages/runtime/container-runtime/src/containerRuntime.ts
@@ -1217,7 +1217,7 @@ export class ContainerRuntime
 		referenceSequenceNumber?: number,
 	) => number;
 	/**
-	 * Do not call directly - use submitAddressesSignal
+	 * Do not call directly - use {@link ContainerRuntime.submitEnvelopedSignal}
 	 */
 	private readonly submitSignalFn: (content: ISignalEnvelope, targetClientId?: string) => void;
 	public readonly disposeFn: (error?: ICriticalContainerError) => void;