Skip to content

Tweak docs on processMessagesCore#26525

Open
CraigMacomber wants to merge 5 commits intomicrosoft:mainfrom
CraigMacomber:processMessagesCore-docs
Open

Tweak docs on processMessagesCore#26525
CraigMacomber wants to merge 5 commits intomicrosoft:mainfrom
CraigMacomber:processMessagesCore-docs

Conversation

@CraigMacomber
Copy link
Contributor

@CraigMacomber CraigMacomber commented Feb 24, 2026

Description

Adjust the docs on processMessagesCore to make more sense to callers (not just be for implementers),
and to make more sense for implementers since the method is abstract and must be implemented.
Docs now provide a bit of higher-level context to how these fits into fluid (that is how ops are sequenced) and note some TODOs for future work.

Reviewer Guidance

The review process is outlined on this wiki page.

Copilot AI review requested due to automatic review settings February 24, 2026 18:36
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR improves the documentation for the processMessagesCore abstract method in SharedObjectCore to make it more understandable for implementers. The documentation now provides higher-level context about how ops are sequenced by the Fluid service, clarifies that ops may be local or remote (but must be sequenced), and adds TODOs for future improvements related to documentation and performance optimization.

Changes:

  • Rewrote the summary and description of processMessagesCore to focus on what the method does (applying sequenced ops) rather than just instructing derived classes to override it
  • Added context explaining that ops have been sequenced by the service and may be local or remote
  • Updated the parameter documentation to be clearer
  • Added TODO comments for future documentation improvements and performance optimization opportunities
  • Removed an inconsistent empty line after the onDisconnect method's JSDoc comment
Comments suppressed due to low confidence (1)

packages/dds/shared-object-base/src/sharedObject.ts:415

  • Spelling error: "cental" should be "central".
	 * TODO: We should have cental linkable documentation (and ideally types) for the special cases of `IRuntimeMessageCollection`

* @privateRemarks
* TODO: We should have central linkable documentation (and ideally more specific types) for the
* "grouped batch" and "bunch" cases of `IRuntimeMessageCollection`.
* TODO:Performance: AB#59783: Allowing this to process more messages at once (more than the current definition of 'bunch') could improve performance of clients which fall behind,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This TODO should not be added here. I can't say for sure if the description in AB#59783 can actually be integrated into bunching or is a completely separate feature. The options mentioned there looks fine in theory but in practice, they may not work or may not be worth doing because it likely covers a very small set of scenarios.
So, I would not add this TODO here until at least the general direction of that work item is more defined. Adding it before that gives the impression that there is more coming which may not be the case.

Copy link
Contributor Author

@CraigMacomber CraigMacomber Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All possible ways to implement that work item involve changing what is passed in here (regardless of if its larger bunches or multiple bunches). It will deliver a large and important performance improvement generally (make slow clients much more able to keep up with lots of tree edits) which is being funded as part of a feature I own (text) where I have measured it would be a large win already. I have an active work item tracking implementing this, and plan to attempt it soon. If that attempt fails I will clean this up along with the work item itself.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For some context, I am making this PR because I was reading this code as the first steps of starting that implementation work.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, personally I think linking a work item for future work in impacting a part of the code is a good thing to do, even if that work item isn't scheduled and likely to happen soon like this one is. If someone wants to know if/when it will happen, they can check the work item to see when/if its scheduled. Linking such items helps prevent redundant work items or implementation and ensures if someone does implement this, they will know about the item and know to coordinate with its owner (if any) and adjust or close if when they are done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants