Improve summary documentation

[tyler-cai-microsoft]

AB#15222

Improve summarizer documentation

• SummaryTreeBuilder documentation
• Other summary cleanup

[msfluid-bot]

Code Coverage Summary

↓ packages.runtime.runtime-utils.src:
Line Coverage Change: 0.04%    Branch Coverage Change: -0.06%

Metric Name	Baseline coverage	PR coverage	Coverage Diff
Branch Coverage	93.93%	93.87%	↓ -0.06%
Line Coverage	97.83%	97.87%	↑ 0.04%

---

Baseline commit: c7730cc
Baseline build: 306006
Happy Coding!!

Code coverage comparison check passed!!

[msfluid-bot]

⯅ @fluid-example/bundle-size-tests: +245 Bytes

Metric Name	Baseline Size	Compare Size	Size Diff
aqueduct.js	464.33 KB	464.36 KB	⯅ +35 Bytes
azureClient.js	563.18 KB	563.23 KB	⯅ +49 Bytes
connectionState.js	724 Bytes	724 Bytes	■ No change
containerRuntime.js	262.48 KB	262.5 KB	⯅ +14 Bytes
fluidFramework.js	426.84 KB	426.85 KB	⯅ +14 Bytes
loader.js	134.18 KB	134.19 KB	⯅ +14 Bytes
map.js	42.71 KB	42.71 KB	⯅ +7 Bytes
matrix.js	148.36 KB	148.36 KB	⯅ +7 Bytes
odspClient.js	528.97 KB	529.02 KB	⯅ +49 Bytes
odspDriver.js	97.88 KB	97.9 KB	⯅ +21 Bytes
odspPrefetchSnapshot.js	42.81 KB	42.83 KB	⯅ +14 Bytes
sharedString.js	164.26 KB	164.27 KB	⯅ +7 Bytes
sharedTree.js	417.3 KB	417.3 KB	⯅ +7 Bytes
Total Size	3.37 MB	3.37 MB	⯅ +245 Bytes

---

Baseline commit: c7730cc

Generated by 🚫 dangerJS against e27d50f

[CraigMacomber]

Nothing in this doc comment or signature explains why "blob" is mentioned here. Or what an attachment is. Or how you get its id.

Linking to ISummaryAttachment or even
Linking to ISummaryAttachment.id would probably help. Also if this has nothing to do with ISummaryBlob, avoiding the term blob would prabably be good.

Also given that ISummaryAttachment.id is undocumented, adding a doc to it and linking it would be good.

Note that ISummaryAttachment.id is read/write, so someone not knowing better could try and set the id to what ever they want, which I assume wouldn't work. Making its docs clear about that would be good (maybe fix the field to be readonly: its kinda late for that so if changes it would gets its own PR and go through API review).

Also seems odd that when adding blobs and handles you provide the key under which the blob will be stored, but when adding an attachment, it puts in under a key it generates itself in an undocumented way.

It seems like a really odd choice for this method to pick the key for you, and the rest to require the key.

If I want to store some attachment as part of my summary, how would the loading code read it back from the summary without knowing the key? This seems hard to use and inconsistent with the other APIs. If there is a reason it works this way, the docs should probably note it.

[CraigMacomber]

Regardless of these issues, this PR is a clear improvement, so I'll approve.

[tyler-cai-microsoft]

Also seems odd that when adding blobs and handles you provide the key under which the blob will be stored, but when adding an attachment, it puts in under a key it generates itself in an undocumented way.

I don't know enough historical context to document this part, so I'm going to leave it as is here.

[Josmithr]

Should we expand on what the path keys are? Any invariants for those keys?

[Josmithr]

Nit: I would recommend rephrasing this in terms of what it does, rather than when it should be called. Those details could be added in a @remarks block if they are useful, but the core part of the comment should be in terms of the method's semantics.

[Josmithr]

+1 to Craig's comment. Left some suggestions, but this is a clear improvement! Thank you very much for adding documentation!!!

[github-actions]

🔗 Found some broken links! 💔

Run a link check locally to find them. See
https://github.com/microsoft/FluidFramework/wiki/Checking-for-broken-links-in-the-documentation for more information.

linkcheck output

> fluidframework-docs@0.25.0 ci:linkcheck /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test ci:start 1313 linkcheck:full

1: starting server using command "npm run ci:start"
and when url "[ 'http://127.0.0.1:1313' ]" is responding with HTTP status code 200
running tests using command "npm run linkcheck:full"


> fluidframework-docs@0.25.0 ci:start
> http-server ./public --port 1313 --silent


> fluidframework-docs@0.25.0 linkcheck:full
> npm run linkcheck:fast -- --external


> fluidframework-docs@0.25.0 linkcheck:fast
> linkcheck http://localhost:1313 --skip-file skipped-urls.txt --external

Crawling...

http://localhost:1313/community/
- (124:32) 'Microsof..' => https://opensource.microsoft.com/codeofconduct/ (connection failed)


Stats:
  443722 links
    3414 destination URLs
       2 URLs ignored
       1 warnings
       1 errors

 ELIFECYCLE  Command failed with exit code 1.