{"record":{"id":"c483ff40c7438973","repo":"astral-sh/ruff","slug":"expected-doc-attribute-to-be-in-the-form-of-doc","errorCode":null,"errorMessage":"expected doc attribute to be in the form of #[doc = \"...\"]","messagePattern":"expected doc attribute to be in the form of #\\[doc = \"\\.\\.\\.\"\\]","errorType":"exception","errorClass":"syn::Error","httpStatus":null,"severity":"error","filePath":"crates/ruff_macros/src/rule_namespace.rs","lineNumber":174,"sourceCode":"                match self { #url_match_arms }\n            }\n        }\n    })\n}\n\n/// Parses an attribute in the form of `#[doc = \" [name](https://example.com/)\"]`\n/// into a tuple of link label and URL.\nfn parse_doc_attr(doc_attr: &Attribute) -> syn::Result<(String, String)> {\n    let Meta::NameValue(MetaNameValue {\n        value:\n            syn::Expr::Lit(ExprLit {\n                lit: Lit::Str(doc_lit),\n                ..\n            }),\n        ..\n    }) = &doc_attr.meta\n    else {\n        return Err(Error::new(\n            doc_attr.span(),\n            r#\"expected doc attribute to be in the form of #[doc = \"...\"]\"#,\n        ));\n    };\n    parse_markdown_link(doc_lit.value().trim())\n        .map(|(name, url)| (name.to_string(), url.to_string()))\n        .ok_or_else(|| {\n            Error::new(\n                doc_lit.span(),\n                \"expected doc comment to be in the form of \\\n                `/// [name](https://example.com/)`\",\n            )\n        })\n}\n\nfn parse_markdown_link(link: &str) -> Option<(&str, &str)> {\n    link.strip_prefix('[')?.strip_suffix(')')?.split_once(\"](\")\n}","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/astral-sh/ruff/blob/26f38c119cac42e4d320ba08f09224fdec74af2c/crates/ruff_macros/src/rule_namespace.rs#L156-L192","documentation":"The rule-namespace derive macro parses a variant's `#[doc]` attribute expecting the literal form `#[doc = \"...\"]` (i.e. a name-value meta holding a string literal). If the doc attribute uses another meta form — such as a `///` comment expanded into `#[doc = ...]` with unexpected tokens, or a structured doc attribute — the macro aborts with this message at the doc attribute's span.","triggerScenarios":"A variant's doc attribute's meta does not match `Meta::NameValue` with a `Lit::Str` value. Raised in `parse_doc_attr` (rule_namespace.rs:174), called from `derive_impl` for each non-Ruff/Numpy variant.","commonSituations":"Writing `/// text` where text is not the expected link (this usually hits error 233 instead, but malformed attributes hit here); using `#[doc = ...]` with a non-string literal like `#[doc = 5]`; macro-generated doc attributes with unusual tokens.","solutions":["Write the doc comment as a plain string-literal doc: `/// [Name](https://url)` so it expands to `#[doc = \"[Name](https://url)\"]`.","Remove any custom/structured `#[doc(...)]` attribute forms on the variant.","Rebuild; if the error persists, inspect the exact attribute syntax on the reported span."],"exampleFix":"// before\n#[doc = 42]\nMyLinter,\n// after\n/// [MyLinter](https://docs.example.com/mylinter)\n#[prefix = \"MYL\"]\nMyLinter,","handlingStrategy":"validation","validationCode":"// Validate doc attribute shape before compiling:\n// expect exactly: #[doc = \"...string...\"] i.e. plain /// comment, no #[doc(...)] structured form.","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use plain `///` doc comments only; avoid hand-written #[doc(...)] attributes on variants.","Keep the doc value a simple string literal (no macro-generated docs)."],"tags":["proc-macro","compile-time","rust","attribute-parsing"],"backgroundTag":"invalid-attribute-format","analyzedSha":"26f38c119cac42e4d320ba08f09224fdec74af2c","analyzedAt":"2026-09-05T10:32:37.492Z","contentChangedAt":"2026-09-05T10:32:37.492Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}