docs(formatter,oxfmt): record embed-layer decisions in place (#25422)

Just notes.

apps/oxfmt/AGENTS.md

@@ -56,6 +56,7 @@ Three roots install `SessionServices`, all via `embed/services.rs::for_root` (on
 
 Which languages may dispatch AT ALL from a given host is the host crate's own gate (e.g. `oxc_formatter_css` dispatches only `yaml`/`toml` front matter); the shared `route()` table then decides who serves the language. Adding a dispatch call to a host crate is therefore a routing decision (check `route()` and the embedded conformance when doing so. A root needing a bespoke service set would assemble the `SessionServices` struct literally), none does today.
 `embeddedLanguageFormatting: off` installs no dispatcher, every builder consults the same off-gate, `ResolvedDispatchConfig::is_embedded_formatting_enabled`.
+Tracing span namespaces: `oxfmt::embed::` = pure Rust work, `oxfmt::external::` = napi-crossing calls.
 
 Per-language options are NOT built up front: `ResolvedDispatchConfig` maps them lazily at dispatch time (`OnceLock`-memoized) from the host file's resolved config, including the Prettier options JSON for the JS-side consumers. `src/core/external_formatter.rs` bridges the napi callbacks into these factories.
 

crates/oxc_formatter/src/formatter/jsdoc/serialize.rs

@@ -73,6 +73,7 @@ impl<'a, 'o> JsdocFormatter<'a, 'o> {
         session: &'o FormatSession<'a>,
         available_width: usize,
     ) -> Self {
+        // NOTE: `jsdocPrintWidth` (`jsdocPrintWidth ?? printWidth`) is not yet ported
         let wrap_width = available_width.saturating_sub(LINE_PREFIX_LEN);
         // Use commentContentPrintWidth (= wrap_width) as the line width for type
         // formatting, matching upstream's `formatType()` which passes

crates/oxc_formatter/src/print/template/embed/graphql.rs

@@ -72,7 +72,8 @@ pub(super) fn format_graphql_doc<'a>(
 
     // Phase 2+3: Build `ir_parts`, one dispatch per non-comment quas.
     // (any failure keeps the whole template verbatim:
-    // the quasis are one interleaved template, so degradation is all-or-nothing)
+    // the quasis are one interleaved template, so degradation is all-or-nothing.
+    // Discarding docs already consumed via `into_doc` is safe, see its rustdoc)
     // Comment-only quasis are synthesized locally.
     // The IR is re-inserted into a JS template literal built from `.cooked` values,
     // so template-literal characters (`` ` ``, `${`, `\`) are re-escaped here

crates/oxc_formatter_core/src/embedded.rs

@@ -108,6 +108,11 @@ impl<'a> DispatchResult<'a> {
     /// moves the child's pre-sort Tailwind classes into the parent's class space and hands out the doc.
     /// Folding the merge into the only way to get the doc makes a forgotten merge unrepresentable.
     /// The entry formatter's document then sorts all collected classes in one host-supplied batch.
+    ///
+    /// A consumer may DISCARD the returned doc afterwards (an all-or-nothing embed site keeping its template verbatim):
+    /// the already-merged classes stay as unreferenced collector entries, which are inert.
+    /// The sorter reorders classes WITHIN each string, never the vector,
+    /// so indices stay stable and unprinted entries never reach the output.
     pub fn into_doc(
         mut self,
         collector: &mut dyn TailwindCollector,