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

[jason-ha]

• removes @internal where API is not package exported and adding real notes where none were.
• adds documentation to exported APIs

Follow-up for #24399 and #24710

[Copilot]

Pull Request Overview

This PR improves the documentation of exported APIs and removes misleading @internal markers for non-package exported interfaces, clarifying usage notes for clients.

• Removes misleading internal tags from API documentation
• Adds detailed @remarks sections to guide proper usage of exported APIs
• Updates comments across multiple modules to better describe runtime and protocol behaviors

Reviewed Changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/runtime/container-runtime-definitions/src/containerExtension.ts	Added @remarks to clarify usage of unverified brands
packages/framework/presence/src/valueManager.ts	Removed internal tags from utility functions
packages/framework/presence/src/types.ts	Removed @internal from shared types documentation
packages/framework/presence/src/systemWorkspace.ts	Updated comments to reflect public API usage
packages/framework/presence/src/stateDatastore.ts	Enhanced documentation for local state update options
packages/framework/presence/src/protocol.ts	Refined documentation on datastore and protocol messages
packages/framework/presence/src/presenceStates.ts	Updated comments to better document local update and state merging
packages/framework/presence/src/presenceManager.ts	Removed unnecessary internal markers in manager APIs
packages/framework/presence/src/presenceDatastoreManager.ts	Updated contract documentation for datastore management
packages/framework/presence/src/presence.ts	Removed internal tag from attendee type documentation
packages/framework/presence/src/internalUtils.ts	Cleared internal comments from utility helpers
packages/framework/presence/src/internalTypes.ts	Revised documentation for internal types with public usage notes
packages/framework/presence/src/datastoreSupport.ts	Added descriptive comments for factory and helper classes
packages/framework/presence/src/broadcastControls.ts	Updated class comments for broadcast control implementations
packages/framework/fluid-static/src/types.ts	Revised internal entry point documentation

[tylerbutler]

All nits and typos. I started changing the punctuation of the comments to be consistent (always have a period) but stopped when I realized there were a lot and there's inconsistency in the file already. You can decide how to proceed. Feel free to ignore the punctuation-related suggestions I made.

[jason-ha]

All nits and typos. I started changing the punctuation of the comments to be consistent (always have a period) but stopped when I realized there were a lot and there's inconsistency in the file already. You can decide how to proceed. Feel free to ignore the punctuation-related suggestions I made.

As I was adding comments to things I was using punctuation when there was a sentence and not when there is a phrase. Actually, removed some to try to be consistent. Later I was finding more cases where there were periods for non-sentences. Is this somewhere in style guide? Also happy to work toward a standard.

[tylerbutler]

All nits and typos. I started changing the punctuation of the comments to be consistent (always have a period) but stopped when I realized there were a lot and there's inconsistency in the file already. You can decide how to proceed. Feel free to ignore the punctuation-related suggestions I made.

As I was adding comments to things I was using punctuation when there was a sentence and not when there is a phrase. Actually, removed some to try to be consistent. Later I was finding more cases where there were periods for non-sentences. Is this somewhere in style guide? Also happy to work toward a standard.

Great question. @Josmithr, @WayneFerrao do we have any guidance for docstrings already?

[jason-ha]

All nits and typos. I started changing the punctuation of the comments to be consistent (always have a period) but stopped when I realized there were a lot and there's inconsistency in the file already. You can decide how to proceed. Feel free to ignore the punctuation-related suggestions I made.

As I was adding comments to things I was using punctuation when there was a sentence and not when there is a phrase. Actually, removed some to try to be consistent. Later I was finding more cases where there were periods for non-sentences. Is this somewhere in style guide? Also happy to work toward a standard.

Great question. @Josmithr, @WayneFerrao do we have any guidance for docstrings already?

One thing I see I did in the past was to use <the name of the API> is in the "title" comment. It looks like:

/**
 * Foo is a stand-in for a random interface.
 */
export interface Foo {

and makes a full sentence. But no idea if we like that broadly.

I updated packages/framework/presence/src/datastoreSupport.ts to have that sentence pattern to see how it looks/feels.

[Josmithr]

All nits and typos. I started changing the punctuation of the comments to be consistent (always have a period) but stopped when I realized there were a lot and there's inconsistency in the file already. You can decide how to proceed. Feel free to ignore the punctuation-related suggestions I made.

As I was adding comments to things I was using punctuation when there was a sentence and not when there is a phrase. Actually, removed some to try to be consistent. Later I was finding more cases where there were periods for non-sentences. Is this somewhere in style guide? Also happy to work toward a standard.

Great question. @Josmithr, @WayneFerrao do we have any guidance for docstrings already?

One thing I see I did in the past was to use <the name of the API> is in the "title" comment. It looks like:

/**
 * Foo is a stand-in for a random interface.
 */
export interface Foo {

and makes a full sentence. But no idea if we like that broadly.

I updated packages/framework/presence/src/datastoreSupport.ts to have that sentence pattern to see how it looks/feels.

Sorry, missed this before. I'll add a task to write something up about this. Since the resulting docs appear unedited on our site, my guidance is always to consider that when crafting the docs. For something that is intended as a brief summary (i.e. the main comment component), I think something like "A stand-in for a random interface." is better than "Foo is a stand-in...". But in places where we're describing things in more detail, complete sentence structure makes more sense.

But yeah, we need documented guidance here and we don't have it.