docs: Expand error and assertion guidance documentation

[Joshua Smithrud (Josmithr)]

Follow-up to #28245

[github-actions]

Hi! Thank you for opening this PR. Want me to review it?

Based on the diff (144 lines, 3 files), I've queued these reviewers:

• Correctness — logic errors, race conditions, lifecycle issues
• Security — vulnerabilities, secret exposure, injection
• API Compatibility — breaking changes, release tags, type design
• Performance — algorithmic regressions, memory leaks
• Testing — coverage gaps, hollow tests

How this works

• Adjust the reviewer set by ticking/unticking boxes above. Reviewer toggles alone don't trigger anything.

• Tick Start review below to dispatch the review fleet.

• After review finishes, tick Start review again to request another run — it auto-resets after each dispatch.

• This comment updates as new commits land; your reviewer selections are preserved.

• Start review

[Copilot]

🟡 Changes recommended

The debugAssert example does not type-check, and several documentation consistency issues remain.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Expands Fluid Framework guidance for errors, assertions, and TSDoc @throws usage.

Changes:

• Adds error and assertion usage guidance.
• Documents TSDoc @throws conventions.
• Clarifies inline assertion documentation practices.

File summaries

File	Summary
docs/content/Guidelines/Documentation-Guidelines/Documenting-TypeScript/TSDoc-Guidelines.md	Adds @throws guidance and examples.
docs/content/Guidelines/Documentation-Guidelines/Documenting-TypeScript.md	Clarifies assertion-related documentation.
docs/content/Guidelines/Coding-Guidelines.md	Expands error and assertion recommendations.

Review details

Suppressed comments (3)

docs/content/Guidelines/Coding-Guidelines.md:729

• This example repeats the same inconsistency: the surrounding guidance requires linking supported error types, but the example uses plain-code RangeError. Use a TSDoc link here as well so the coding-guideline example demonstrates the documented convention.

 * @throws A `RangeError` if the index is not an integer or is outside the supported range.

docs/content/Guidelines/Coding-Guidelines.md:613

• This example does not type-check against debugAssert's signature (predicate: () => true | { toString(): string }): the comparison produces a general boolean, so the || expression is boolean | string and may return false, which is not assignable to the required predicate result. Use a conditional that returns the literal true on success, for example cachedValues.size <= capacity ? true : "The cache must stay within capacity.".

debugAssert(() => cachedValues.size <= capacity || "The cache must stay within capacity.");

docs/content/Guidelines/Documentation-Guidelines/Documenting-TypeScript/TSDoc-Guidelines.md:250

• The new guidance says to use {@link ...} for error types available at the API's support level, but this example formats the available built-in RangeError as plain code. Please make the example follow the rule it introduces, for example by linking RangeError.

 * @throws A `RangeError` if index is not an integer or is outside the supported range.

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

$ start-server-and-test "npm run serve -- --host 127.0.0.1 --no-open" http://127.0.0.1:3000 check-links
1: starting server using command "npm run serve -- --host 127.0.0.1 --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"


> fluid-framework-website@0.0.0 serve
> docusaurus serve --host 127.0.0.1 --no-open

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

> fluid-framework-website@0.0.0 check-links
> linkcheck http://127.0.0.1:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  658102 links
    3579 destination URLs
    3898 URLs ignored
       0 warnings
       0 errors