Repository navigation
docs: remove rustdoc hidden lines from markdown examples - #26
Merged
hmziqrs merged 6 commits intoOct 12, 2026
Merged
Conversation
The unquoted (v0.3.0): sequence in the description value breaks yaml frontmatter parsers; github's preview refused the file outright.
The # line idiom only hides on docs.rs; github and the starlight site render it as literal '#' comment noise. Snippets in the four published readmes, the root readme, nine docs pages, and the extensions skill are now self-contained on every surface. unimplemented!() stubs are replaced with visible function signatures. Also fixes a dangling [`tempfile`] reference-style link in the persist readme (docs.rs now shows the example boilerplate that was previously hidden there).
astro.config.mjs uses directory output with trailingSlash ignore, not flat file output.
hmziqrs
approved these changes
Oct 12, 2026
Follow-up to the judge defers: commented-out hydrate call compressed to a 3-line constraint note, trailing enumeration labels removed from the retry/query-key/observer/persister fences, and now-unread closure params renamed to _signal/_entity. No fact loss: the tolerant-load contract lives in the prose above the fence, the retry defaults in the api docs.
hmziqrs
approved these changes
Oct 12, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The repo's markdown used rustdoc's
#hidden-line idiom to tuck example scaffolding out of sight. That only works on docs.rs, where the READMEs are embedded via#[doc = include_str!]. GitHub and the Starlight site render those lines literally as# use gpui::...comment noise. A repo-wide fence-aware scan found 55 such lines across 14 files (15 counting the yaml fix below).Separately, the
gpui-queryskill pack's frontmatterdescription:value contained an unquoted(v0.3.0):sequence. That breaks yaml parsers; github's preview refused the file with "mapping values are not allowed in this context at line 2 column 78".Changes
description:value. No wording change; 750 chars, under the 1024 limit.usegroups; hiddenfn doc(...)wrappers become real named functions; same code otherwise.unimplemented!()context stubs replaced with visible function signatures (observers, installation, quick-start, query-keys) or a plain leading comment (select-pattern).fetch_usersstub line made visible.[`tempfile`]had no link reference definition and rendered as literal brackets; now a real link to docs.rs/tempfile.build.format: "file";web/astro.config.mjsuses"directory"+trailingSlash: "ignore". Corrected to match.Verification
#lines inside rust fences; all 24 frontmatters parse clean underyaml.safe_load.cargo test --all-features: 760 unit tests and all 37 doctests green. Every rewritten README fence compiles as a doctest, so the examples stay machine-checked.cargo clippy --all-features --all-targets -- -D warnings: clean.cargo doc --all-features --no-deps: clean.Tradeoff
docs.rs now shows the example boilerplate (imports, scaffold structs) that the
#lines used to hide. GitHub and docs.rs render identical, complete examples.