Replace fabricated code samples in docs with links to actual source files

[kixelated]

The documentation had many code examples that were written by hand and
didn't match the actual API, leading to constantly incorrect docs.
Replace them with GitHub links to real example files, test suites, and
config files that are compiled/tested and stay up to date.

Files updated: doc/js/@moq/lite.md, doc/js/@moq/token.md, doc/js/index.md,
doc/rs/crate/hang.md, doc/rs/crate/libmoq.md, doc/rs/crate/moq-lite.md,
doc/rs/crate/moq-mux.md, doc/rs/crate/moq-token.md,
doc/rs/crate/web-transport.md, doc/app/relay/auth.md,
doc/app/relay/config.md

https://claude.ai/code/session_012bjdV8HhxAUCenrhVBELw5

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9423b37f-d95f-404c-bee4-5536e1b16fdf

📥 Commits

Reviewing files that changed from the base of the PR and between 2464081 and 01be63b.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (5)

• doc/js/@moq/lite.md
• doc/rs/crate/moq-token.md
• rs/moq-token/Cargo.toml
• rs/moq-token/examples/asymmetric.rs
• rs/moq-token/examples/basic.rs

✅ Files skipped from review due to trivial changes (2)

• rs/moq-token/Cargo.toml
• doc/rs/crate/moq-token.md

🚧 Files skipped from review as they are similar to previous changes (2)

• doc/js/@moq/lite.md
• rs/moq-token/examples/basic.rs

---

Walkthrough

The pull request refactors documentation by replacing many inline code and TOML examples with links to external example files (primarily under demo/relay/, js/.../examples/, and rs/.../examples/). Several Rust and TypeScript snippets were removed from docs and replaced by references. Two new Rust example binaries were added under rs/moq-token/examples/ (basic.rs and asymmetric.rs) demonstrating symmetric and asymmetric JWT signing/verification. rs/moq-token/Cargo.toml gained a [dev-dependencies] entry for anyhow.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: replacing hand-written code samples in documentation with links to actual source files.
Description check	✅ Passed	The description directly relates to the changeset by explaining the problem (hand-written examples that don't match the API) and the solution (replacing with links to real, tested files).

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/replace-docs-code-samples-flDGS

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/replace-docs-code-samples-flDGS

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

rs/moq-token/examples/asymmetric.rs (1)

9-9: Align binary error type with repo convention (anyhow::Result).

Line 9 should use anyhow::Result<()> for consistency with other binaries/examples.

♻️ Proposed fix

-fn main() -> moq_token::Result<()> {
+fn main() -> anyhow::Result<()> {

As per coding guidelines **/*.rs: "Use thiserror with #[from] for library crates, anyhow for binaries."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@rs/moq-token/examples/asymmetric.rs` at line 9, Change the binary's main
signature from moq_token::Result<()> to anyhow::Result<()> by updating fn main()
-> moq_token::Result<()> to fn main() -> anyhow::Result<()> and ensure anyhow is
available (add anyhow to Cargo.toml dependencies if missing); update any local
use statements if you prefer a type alias (e.g., add use anyhow::Result;) so the
example binary follows the repo convention.

doc/rs/crate/moq-token.md (1)

148-148: Add one concrete JWKS expectation in this section.

After removing the inline sample, this is a bit underspecified. Add a short sentence clarifying the relay expects a JWKS JSON endpoint (and that keys are selected by kid) to keep setup unambiguous.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@doc/rs/crate/moq-token.md` at line 148, Clarify that the relay expects a JWKS
JSON endpoint that serves a JWK Set (JSON with a "keys" array) and that the
relay selects the verification key by matching the token's "kid" to an entry in
that array; update the sentence near the existing mention of "host a JWK set and
configure the relay to fetch keys from a URL" to state this explicitly and
reference key selection by "kid" so readers know the endpoint format and
selection mechanism.

doc/app/relay/auth.md (1)

171-174: Prefer version-stable repo-relative links over blob/main URLs.

These links will always resolve to the latest main, which can drift from the doc version being viewed. Prefer repo-relative/internal doc links so examples stay version-aligned with the page.

Suggested direction

-- **Development** - [`demo/relay/root.toml`](https://github.com/moq-dev/moq/blob/main/demo/relay/root.toml)
+- **Development** - [`demo/relay/root.toml`](/demo/relay/root.toml)

-- [`rs/moq-token/examples/basic.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-token/examples/basic.rs)
+- [`rs/moq-token/examples/basic.rs`](/rs/moq-token/examples/basic.rs)

Also applies to: 180-185

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@doc/app/relay/auth.md` around lines 171 - 174, Replace the absolute blob/main
GitHub URLs in doc/app/relay/auth.md with repo-relative links so they remain
version-stable; specifically update the two links to demo/relay/root.toml and
demo/relay/prod.toml to use repository-relative paths (e.g., /moq/tree/<path> or
just the relative path within the repo/docs system) instead of
https://github.com/.../blob/main/... and apply the same change for the other
occurrences mentioned (lines ~180-185) so examples stay aligned with the doc
version.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@doc/js/`@moq/lite.md:
- Line 53: The wording incorrectly states that named streams (tracks) are
"created via `subscribe`"; update the sentence in doc/js/@moq/lite.md so it
clarifies that tracks are created/published by the publisher (e.g., via the
publish/create API) and are consumed by subscribers using `subscribe` — replace
"created via `subscribe`" with phrasing like "published by the publisher and
consumed via `subscribe`" and mention `subscribe` only as the consumer-side
operation.

---

Nitpick comments:
In `@doc/app/relay/auth.md`:
- Around line 171-174: Replace the absolute blob/main GitHub URLs in
doc/app/relay/auth.md with repo-relative links so they remain version-stable;
specifically update the two links to demo/relay/root.toml and
demo/relay/prod.toml to use repository-relative paths (e.g., /moq/tree/<path> or
just the relative path within the repo/docs system) instead of
https://github.com/.../blob/main/... and apply the same change for the other
occurrences mentioned (lines ~180-185) so examples stay aligned with the doc
version.

In `@doc/rs/crate/moq-token.md`:
- Line 148: Clarify that the relay expects a JWKS JSON endpoint that serves a
JWK Set (JSON with a "keys" array) and that the relay selects the verification
key by matching the token's "kid" to an entry in that array; update the sentence
near the existing mention of "host a JWK set and configure the relay to fetch
keys from a URL" to state this explicitly and reference key selection by "kid"
so readers know the endpoint format and selection mechanism.

In `@rs/moq-token/examples/asymmetric.rs`:
- Line 9: Change the binary's main signature from moq_token::Result<()> to
anyhow::Result<()> by updating fn main() -> moq_token::Result<()> to fn main()
-> anyhow::Result<()> and ensure anyhow is available (add anyhow to Cargo.toml
dependencies if missing); update any local use statements if you prefer a type
alias (e.g., add use anyhow::Result;) so the example binary follows the repo
convention.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b48485b5-d68a-44e1-a469-ceb99c22b8e2

📥 Commits

Reviewing files that changed from the base of the PR and between bbe61c4 and 2464081.

📒 Files selected for processing (13)

• doc/app/relay/auth.md
• doc/app/relay/config.md
• doc/js/@moq/lite.md
• doc/js/@moq/token.md
• doc/js/index.md
• doc/rs/crate/hang.md
• doc/rs/crate/libmoq.md
• doc/rs/crate/moq-lite.md
• doc/rs/crate/moq-mux.md
• doc/rs/crate/moq-token.md
• doc/rs/crate/web-transport.md
• rs/moq-token/examples/asymmetric.rs
• rs/moq-token/examples/basic.rs