docs(tree): updates and fixes #23455

yann-achard-MS · 2025-01-04T01:28:01Z

Description

Updates and fixes to the existing docs.

Breaking Changes

None

Copilot wasn't able to review any files in this pull request.

Files not reviewed (6)

docs/docs/data-structures/tree/events.mdx: Language not supported
docs/docs/data-structures/tree/nodes.mdx: Language not supported
docs/docs/data-structures/tree/reading-and-editing.mdx: Language not supported
docs/docs/data-structures/tree/schema-definition.mdx: Language not supported
docs/docs/data-structures/tree/transactions.mdx: Language not supported
docs/docs/data-structures/tree/undo-redo.mdx: Language not supported

taylorsw04 · 2025-01-06T17:08:52Z

docs/docs/data-structures/tree/reading-and-editing.mdx

@@ -3,7 +3,7 @@ title: Reading and Editing
 sidebar_position: 4
 ---

-The `TreeView` object and its children provide methods that enable your code to add nodes to the tree, remove nodes, and move nodes within the tree. You can also set and read the values of leaf nodes. The APIs have been designed to match as much as possible the syntax of TypeScript primitives, objects, maps, and arrays; although some editing APIs are different for the sake of making the merge semantics clearer.
+The `TreeView` object and its children expose properties and methods that allows applications read and edit the tree. The APIs have been designed to match as much as possible the syntax of TypeScript primitives, objects, maps, and arrays; although some editing APIs are different for the sake of making the merge semantics clearer.


Suggested change

The `TreeView` object and its children expose properties and methods that allows applications read and edit the tree. The APIs have been designed to match as much as possible the syntax of TypeScript primitives, objects, maps, and arrays; although some editing APIs are different for the sake of making the merge semantics clearer.

The `TreeView` object and its children expose properties and methods that allow applications read and edit the tree.

The APIs have been designed to match as much as possible the syntax of TypeScript primitives, objects, maps, and arrays (although some editing APIs are different for the sake of making the merge semantics clearer).

taylorsw04 · 2025-01-06T17:12:07Z

docs/docs/data-structures/tree/reading-and-editing.mdx

@@ -52,6 +52,10 @@ We show how to add this note to an array of notes in the tree in [Array node API
 ### Editing Object Properties

 To update the property on an object node, you assign a new node or value to it with the assignment operator (`=`).
+See [here](https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/docs/user-facing/object-merge-semantics.md) for details on the merge semantics of these edits.
+
+Note that if the new value is a node (as opposed to a primitive), then its [status](./nodes.mdx#treestatus) must be `TreeStatus.New`,


Is this important enough to list before the examples? I think allowing readers to digest the code first, and the warning second, might make this less of a rabbit hole.

+1, but this section also requires some deduping with the quick start page so I feel like it's prob fine to make these changes as reminders of info we need to include and rearrange later

Moved it down

jenn-le · 2025-01-06T17:55:53Z

docs/docs/data-structures/tree/events.mdx


-`rootChanged` fires when the root field (the field that contains the root node) changes.
+`rootChanged` fires when the contents root field (the field that contains the root node) change.


is it supposed to be this?

Suggested change

`rootChanged` fires when the contents root field (the field that contains the root node) change.

`rootChanged` fires when the root field contents (the field that contains the root node) change.

Almost :)
I think "the contents of the root field" make the parenthetical that follow flow a bit better

jenn-le · 2025-01-06T17:58:16Z

docs/docs/data-structures/tree/events.mdx

 That is, if a new root node is assigned or the schema changes.
 This will not fire when the node itself changes.

-`changed` fires whenever a change is applied outside of a transaction or when a transaction is committed.
+`commitApplied` fires whenever a change is applied outside of a transaction or when a transaction is committed.


commitApplied is being deprecated in favor of changed because commitApplied doesn't fire for remote changes

Ha thanks, I was confused because the current doc still refers to "commitApplied" at the top.

Oh, but it's an alpha API at the moment. Based on this morning's conversation, the consensus seemed to be that we wouldn't add FF-site docs for alpha APIs.

Ah ok yeah, that makes sense. Hopefully we can make that not alpha soon cause it's very confusing :/

jenn-le · 2025-01-06T17:59:38Z

docs/docs/data-structures/tree/events.mdx

+## Node-Level Events
+
+`SharedTree` supports two node-level events: `nodeChanged` and `treeChanged`.
+These can be subscribed to using the `Tree.on` method, which has the following signature:


I think we should add an example of how to subscribe to the tree level events as well in the section above

jenn-le · 2025-01-06T18:01:10Z

docs/docs/data-structures/tree/nodes.mdx

@@ -10,13 +10,16 @@ See [node types](./node-types.mdx) for details on the types of nodes that can be

 Below are some utilities provided to make working with nodes easier.

-### Node Information
+### `Tree.key`


I'm thinking it'd be better to just have links to the api docs so we're not duplicating any info. It'd be even better if there's a way to embed the docs in pages. @Josmithr do you know if this is a thing?

Yeah, I'm not sure what the best middle ground is between reducing duplication and facilitating using discovery/usage, but embedding or linking to the API docs sounds good.
I don't think we should do that as part of this PR though.

jenn-le · 2025-01-06T18:05:44Z

docs/docs/data-structures/tree/reading-and-editing.mdx

@@ -52,6 +52,10 @@ We show how to add this note to an array of notes in the tree in [Array node API
 ### Editing Object Properties

 To update the property on an object node, you assign a new node or value to it with the assignment operator (`=`).
+See [here](https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/docs/user-facing/object-merge-semantics.md) for details on the merge semantics of these edits.
+
+Note that if the new value is a node (as opposed to a primitive), then its [status](./nodes.mdx#treestatus) must be `TreeStatus.New`,


+1, but this section also requires some deduping with the quick start page so I feel like it's prob fine to make these changes as reminders of info we need to include and rearrange later

jenn-le · 2025-01-06T18:07:27Z

docs/docs/data-structures/tree/reading-and-editing.mdx


 ```typescript
 keys(): IterableIterator<string>
 ```

-Returns an Iterator that contains the keys in the map node. The keys are iterated in the order that they were added.
+Returns an Iterator that contains the keys in the map node.
+We do not make guarantees about the ordering of the keys.


I think specific info like this should be kept on the API docs and we should do more linking

Yeah, agreed. I mostly wanted to stop telling lies, so I'm happy to just remove the lie and not mention the truth here (the API does say "If your usage scenario depends on consistent ordering, you will need to sort these yourself").

Yeah, I like that approach

jenn-le · 2025-01-07T18:09:28Z

docs/docs/data-structures/tree/events.mdx

@@ -5,9 +5,16 @@ sidebar_position: 5

 ## Whole-Tree Events

-The `TreeView` object exposes 2 events that communicate changes that affect the whole tree.
+The `TreeView` object exposes 2 events that communicate changes that affect the whole tree. For example:


I think the section below flows a bit better, in how it introduces the events and then says "here's how you subscribe to them"

jenn-le

looks good to me, just had the one minor comment

github-actions · 2025-01-08T22:12:33Z

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> [email protected] ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> [email protected] serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> [email protected] check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  170508 links
    1603 destination URLs
    1842 URLs ignored
       0 warnings
       0 errors

docs(tree): updates and fixes

39c7d01

github-actions bot added area: website base: main PRs targeted against main branch labels Jan 4, 2025

yann-achard-MS added 2 commits January 3, 2025 17:40

Fix link

05aa7d9

More link fixes

63f024c

yann-achard-MS marked this pull request as ready for review January 6, 2025 16:29

Copilot bot review requested due to automatic review settings January 6, 2025 16:29

Copilot AI reviewed Jan 6, 2025

View reviewed changes

yann-achard-MS requested review from jenn-le, taylorsw04 and nmsimons January 6, 2025 16:30

taylorsw04 reviewed Jan 6, 2025

View reviewed changes

jenn-le reviewed Jan 6, 2025

View reviewed changes

PR feedback

30ec5a2

jenn-le reviewed Jan 7, 2025

View reviewed changes

jenn-le approved these changes Jan 7, 2025

View reviewed changes

Move example TreeView even sub down

1accfc1

yann-achard-MS merged commit ba65d67 into microsoft:main Jan 8, 2025
29 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(tree): updates and fixes #23455

docs(tree): updates and fixes #23455

yann-achard-MS commented Jan 4, 2025

taylorsw04 Jan 6, 2025

yann-achard-MS Jan 7, 2025

taylorsw04 Jan 6, 2025

jenn-le Jan 6, 2025

yann-achard-MS Jan 7, 2025

jenn-le Jan 6, 2025

yann-achard-MS Jan 7, 2025

jenn-le Jan 6, 2025

yann-achard-MS Jan 7, 2025

yann-achard-MS Jan 7, 2025

jenn-le Jan 7, 2025

jenn-le Jan 6, 2025

yann-achard-MS Jan 7, 2025

jenn-le Jan 6, 2025

yann-achard-MS Jan 7, 2025

jenn-le Jan 6, 2025

jenn-le Jan 6, 2025

yann-achard-MS Jan 7, 2025

jenn-le Jan 7, 2025

jenn-le Jan 7, 2025

yann-achard-MS Jan 8, 2025

jenn-le left a comment

github-actions bot commented Jan 8, 2025

	The `TreeView` object and its children expose properties and methods that allows applications read and edit the tree. The APIs have been designed to match as much as possible the syntax of TypeScript primitives, objects, maps, and arrays; although some editing APIs are different for the sake of making the merge semantics clearer.
	The `TreeView` object and its children expose properties and methods that allow applications read and edit the tree.
	The APIs have been designed to match as much as possible the syntax of TypeScript primitives, objects, maps, and arrays (although some editing APIs are different for the sake of making the merge semantics clearer).


		`rootChanged` fires when the root field (the field that contains the root node) changes.
		`rootChanged` fires when the contents root field (the field that contains the root node) change.

docs(tree): updates and fixes #23455

docs(tree): updates and fixes #23455

Conversation

yann-achard-MS commented Jan 4, 2025

Description

Breaking Changes

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jenn-le left a comment

Choose a reason for hiding this comment

github-actions bot commented Jan 8, 2025

linkcheck output