{"record":{"id":"d24797dfa119de85","repo":"typst/typst","slug":"the-stringify-macro-is-not-fully-supported-in-the-typst","errorCode":null,"errorMessage":"the `stringify!` macro is not fully supported in the Typst documentation","messagePattern":"the `stringify!` macro is not fully supported in the Typst documentation","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/typst-macros/src/util.rs","lineNumber":60,"sourceCode":"    let mut doc = String::new();\n\n    // Parse doc comments.\n    for attr in attrs {\n        if let syn::Meta::NameValue(meta) = &attr.meta\n            && meta.path.is_ident(\"doc\")\n        {\n            if let syn::Expr::Lit(lit) = &meta.value\n                && let syn::Lit::Str(string) = &lit.lit\n            {\n                let full = string.value();\n                let line = full.strip_prefix(' ').unwrap_or(&full);\n                doc.push_str(line);\n                doc.push('\\n');\n            } else if let syn::Expr::Macro(expr) = &meta.value\n                && expr.mac.path.is_ident(\"stringify\")\n            {\n                let value = stringify(expr.mac.tokens.clone()).ok_or_else(|| {\n                    Error::new(\n                        expr.span(),\n                        \"the `stringify!` macro is not fully supported in \\\n                         the Typst documentation\",\n                    )\n                })?;\n                doc.push_str(&value);\n                doc.push('\\n');\n            }\n        }\n    }\n\n    Ok(doc.trim().into())\n}\n\n/// Whether an attribute list has a specified attribute.\npub fn has_attr(attrs: &mut Vec<syn::Attribute>, target: &str) -> bool {\n    take_attr(attrs, target).is_some()\n}","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/typst/typst/blob/a73e705a5f3013876e4e38c52758a6706cc03819/crates/typst-macros/src/util.rs#L42-L78","documentation":"This compile-time error is raised by the `documentation` helper in typst-macros when generating Typst documentation from doc comments. When a doc attribute's value is a `stringify!(...)` macro invocation, the helper calls its own `stringify` function to render the tokens; if that function returns `None` (the token stream uses constructs the helper cannot render), it emits this error at the expression's span, indicating the doc string cannot be produced for the Typst docs.","triggerScenarios":"Writing a doc comment whose value expands to `stringify!(...)` — typically via a macro-generated doc attribute or a `doc = stringify!(...)` form — where the inner tokens contain constructs unsupported by the crate's `stringify` renderer (e.g. unusual literals, nested macros, or complex expressions). Called from `Variant`, `create_input_body`, `parse`, `Field`, and `Param` paths of the macro.","commonSituations":"Using `#[doc = stringify!(...)]` or a declarative macro that emits `#[doc = stringify!(...)]` on an `#[elem]`/`#[func]`/`#[ty]` item; codegen tools producing doc attributes that rustc accepts but Typst's documentation extractor cannot render; upgrading Typst and introducing docs features the extractor does not support.","solutions":["Replace the `stringify!(...)` doc attribute with a plain string doc comment (`/// ...` or `#[doc = \"...\"]`) containing the literal text.","Simplify the tokens inside `stringify!(...)` — remove nested macros or unsupported literals — so the helper's `stringify` function can render them.","If the doc attribute is generated by another macro, change that generator to emit plain string literals."],"exampleFix":"// before\n#[doc = stringify!(MY_ELEMENT_DOCS)]\n#[elem]\nstruct MyElem { ... }\n\n// after\n/// Documentation for my element.\n#[elem]\nstruct MyElem { ... }","handlingStrategy":"validation","validationCode":"// Doc values passed to #[elem]/#[func]/#[ty] items must be plain strings.\n// Good: #[doc = \"literal text\"] or /// literal text\n// Bad:  #[doc = stringify!(some_expr)]","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use plain `///` doc comments or `#[doc = \"...\"]` string literals on macro-decorated items.","Avoid `stringify!` and nested macros in doc attributes on `#[elem]`/`#[func]`/`#[ty]` items.","If docs are shared via constants, paste the literal text instead of `stringify!(CONST)`.","Review any codegen that emits doc attributes to ensure it emits plain strings."],"tags":["proc-macro","rust","compile-time","documentation","stringify"],"backgroundTag":"unsupported-operation","analyzedSha":"a73e705a5f3013876e4e38c52758a6706cc03819","analyzedAt":"2026-09-12T11:41:09.893Z","contentChangedAt":"2026-09-12T11:41:09.893Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}