Thank you for the response. Like you said, the details are subtle and require close inspection to get it right here. Going by the links you posted, the revised version of MessageReceived on the TextChatService page is clearer than the old version still active on the TextChannel page. At the risk of sounding nitpicky though, there’s still some ambiguity here:
Fires exclusively on the client when […]
When the sentence starts out like this, it gives the reader the impression that there is going to be a follow-up ‘when’ case in which it’s fired in a context other than ‘exclusively on the client.’ The reader may read those first words and then predict the sentence like so:
“Fires exclusively on the client when X, but when Y happens it could be fired differently like on the client and server or exclusively on the server when Z happens blah blah blah”
This is why I originally separated it into two clauses — there’s no ambiguity even though it does sound awkwardly short:
Maybe this is better:
This event is exclusively fired on the client, and is triggered by two actions: […]
There's one other nitpick about the sentence I noticed:
Fires exclusively on the client when a TextChannel:SendAsync() response is received by the server
*by* the server? This preposition is misleading — the client is receiving a response from the server. Yes, the server responds to the client’s TextChannel:SendAsync call, but then the client receives a response back from the server (presumably the server’s role here is through TextChannel.SendDeliverCallback).
The TextChatMessage parameter is the final result of any functions bound to TextChatService.OnIncomingMessage.
I suppose this detail exists for clarity, and it’s a welcome one for me. However, although the TextChatMessage.OnIncomingMessage error mentioned in the OP has been fixed here, it confusingly removes mention of TextChannel.OnIncomingMessage.
The OnIncomingMessage callback exists on both the TextChatService singleton instance and any TextChannel instances in use. From the page In-Experience Text Chat System:
In the top left you can see there’s a box with both of those callbacks inside it. I think it would make sense to include both in the MessageReceived description for consistency.
As a sidenote, testing seems to show that this flowchart is wrong, as the sender’s client fires OnIncomingMessage immediately without waiting for a server response, but perhaps that’s for another thread.
The blurb here in the summary section is even more ambiguous about MessageReceived:
It still has the grammatical ambiguity issues that I described at the start of this post, but it further doesn’t say which context this event is fired on (the client).
Maybe the ‘run context’ ambiguity problem here would be best solved with a more overarching documentation feature, like implementing those green and blue ribbons that the Studio output uses to indicate run context. Here’s an example:
Again though, probably best saved for another thread.
The link at the top of the TextChatService page has a broken link (access denied):
To learn more, see In-Experience Text Chat.
I dunno what HostId is but I’m not taking any chances if it’s sensitive info :P
I figured I would put this here since it’s still the same page in question from the OP, even if it’s not explicitly about MessageReceived.
Again I know these corrections sound petty or minor, but it can be confusing if the technical details are written ambiguously enough to require testing by the reader to ensure he/she read it correctly.
