From 357cf712e846c53d9f22071bf61586916dc0662f Mon Sep 17 00:00:00 2001 From: Adam Harris Date: Sat, 7 Nov 2026 14:03:26 -0700 Subject: [PATCH] docs(tasks): the lossless envelope's placeholders read as HTML on docs.rs --- ...less-envelope-placeholders-read-as-html.md | 62 +++++++++++++++++++ docs/tasks/tasks.md | 1 + 2 files changed, 63 insertions(+) create mode 100644 docs/tasks/lossless-envelope-placeholders-read-as-html.md diff --git a/docs/tasks/lossless-envelope-placeholders-read-as-html.md b/docs/tasks/lossless-envelope-placeholders-read-as-html.md new file mode 100644 index 00000000..a91b1e50 --- /dev/null +++ b/docs/tasks/lossless-envelope-placeholders-read-as-html.md @@ -0,0 +1,62 @@ +```fig +title = The lossless envelope's placeholders read as HTML on docs.rs +part_of = [Tasks](/docs/tasks/tasks.md) +status = open +created = 2026-11-07 +updated = 2026-11-07 +description = fig_core::lossless's module docs write the envelope schema as a two-space-indented paragraph, so rustdoc passes , and to the browser as HTML tags: docs.rs shows the schema with its placeholders missing, and cargo doc warns three times +``` + +# The lossless envelope's placeholders read as HTML on docs.rs + +**Where.** `rust/fig-core/src/lossless.rs`, lines 34–39 of the module doc. + +The module doc shows the envelope a lossless value travels in: + +```text +//! Envelope schema, as it appears once parsed back into an AST: +//! { "$fig": { "t": "" } } // a null +//! { "$fig": { "t": "", "v": "" } } // an extended scalar +//! where `` is `"null"` and `` is the `ExtKind` field name +``` + +Two spaces of indent is not a code block in Markdown, so the two schema +lines are prose. In prose, ``, `` and `` are HTML tags, +which rustdoc hands to the browser as they stand. A browser draws an unknown +tag as nothing, so the reader sees the schema with its placeholders gone: +`{ “$fig”: { “t”: “” } }`, with the quotes curled, all on the lines of one +paragraph. The sentence after it, which names `` and `` in +backticks, then explains placeholders the reader cannot see. + +## Repro + +On docs.rs, at , +the page's HTML holds the raw tags: + +```text +{ “$fig”: { “t”: “” } } // a null +{ “$fig”: { “t”: “”, “v”: “” } } // an extended scalar +``` + +Locally, at d97b314f: + +```console +$ RUSTDOCFLAGS='-D warnings' cargo doc -p fig-core --no-deps +error: unclosed HTML tag `type` + --> rust/fig-core/src/lossless.rs:35:25 +error: unclosed HTML tag `extkind` + --> rust/fig-core/src/lossless.rs:36:25 +error: unclosed HTML tag `text` + --> rust/fig-core/src/lossless.rs:36:43 +error: could not document `fig-core` +``` + +Without `-D warnings` these are the three warnings `cargo doc` prints for +fig-core. fig's CI runs no `cargo doc` job, so nothing has caught them. + +## Done when + +The schema lines are a fenced code block (or each placeholder is in +backticks), the docs.rs page of the next release shows ``, +`` and ``, and `RUSTDOCFLAGS='-D warnings' cargo doc -p +fig-core --no-deps` passes. diff --git a/docs/tasks/tasks.md b/docs/tasks/tasks.md index 27fabb3f..2d4e307e 100644 --- a/docs/tasks/tasks.md +++ b/docs/tasks/tasks.md @@ -22,6 +22,7 @@ contents > * [A block comment after a one-line container moves inside it](/docs/tasks/a-block-comment-after-a-one-line-container-moves-inside-it.md) > * [A flow insert copies a separator from a nested rule](/docs/tasks/a-flow-insert-copies-a-separator-from-a-nested-rule.md) > * [A comment in an empty container used as a key is dropped](/docs/tasks/a-comment-in-an-empty-key-container-is-dropped.md) +> * [The lossless envelope's placeholders read as HTML on docs.rs](/docs/tasks/lossless-envelope-placeholders-read-as-html.md) ``` # Tasks