From 1e09342541cff87bf1ccf0c0af3af8dc0e1a8dd1 Mon Sep 17 00:00:00 2001 From: Adam Harris Date: Tue, 10 Nov 2026 15:51:37 -0700 Subject: [PATCH] docs(core): fence the lossless envelope schema in a code block The two schema lines in fig_core::lossless's module doc were a two-space-indented paragraph, which Markdown reads as prose, so rustdoc passed , and to the browser as HTML tags and docs.rs drew the schema with its placeholders missing. As a fenced text block they are escaped, and `RUSTDOCFLAGS='-D warnings' cargo doc -p fig-core --no-deps` passes. Closes docs/tasks/lossless-envelope-placeholders-read-as-html.md. --- .../lossless-envelope-placeholders-read-as-html.md | 10 ++++++++-- rust/fig-core/src/lossless.rs | 8 ++++++-- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/tasks/lossless-envelope-placeholders-read-as-html.md b/docs/tasks/lossless-envelope-placeholders-read-as-html.md index a91b1e50..870a3ba7 100644 --- a/docs/tasks/lossless-envelope-placeholders-read-as-html.md +++ b/docs/tasks/lossless-envelope-placeholders-read-as-html.md @@ -1,14 +1,20 @@ ```fig title = The lossless envelope's placeholders read as HTML on docs.rs part_of = [Tasks](/docs/tasks/tasks.md) -status = open +status = done created = 2026-11-07 -updated = 2026-11-07 +updated = 2026-11-10 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 +**Status.** Done, in `docs(core): fence the lossless envelope schema in a code +block`. The two schema lines are a fenced `text` block, so rustdoc escapes +``, `` and ``, and `RUSTDOCFLAGS='-D warnings' cargo doc +-p fig-core --no-deps` passes. The docs.rs page shows them from the next +release. + **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: diff --git a/rust/fig-core/src/lossless.rs b/rust/fig-core/src/lossless.rs index 686f98d5..7e3bbde2 100644 --- a/rust/fig-core/src/lossless.rs +++ b/rust/fig-core/src/lossless.rs @@ -32,8 +32,12 @@ //! pure node-kind transforms. //! //! Envelope schema, as it appears once parsed back into an AST: -//! { "$fig": { "t": "" } } // a null -//! { "$fig": { "t": "", "v": "" } } // an extended scalar +//! +//! ```text +//! { "$fig": { "t": "" } } // a null +//! { "$fig": { "t": "", "v": "" } } // an extended scalar +//! ``` +//! //! where `` is `"null"` and `` is the `ExtKind` field name //! (`offset_datetime`, `enum_literal`, …). `v` carries the scalar's intrinsic //! text verbatim (for a char literal, its decimal codepoint, as fig stores it).