What causes "expected a doc comment" in astral-sh/ruff?

Add a doc comment of the form `/// [Linter Name](https://example.com/docs)` directly above the variant.

astral-sh/ruff · error · syn::Error

expected a doc comment

Error message

expected a doc comment

What it means

The rule-namespace derive macro requires every non-special enum variant to have a doc comment (`/// ...`) whose content is a markdown link naming the linter and linking to its documentation. This error is emitted when a variant has a prefix but no `#[doc]` attribute at all; the doc comment is parsed later into the linter's display name and URL.

Source

Thrown at crates/ruff_macros/src/rule_namespace.rs:93

                }
                Ok(str)
            })
            .collect();
        let prefixes = prefixes?;

        if prefixes.is_empty() {
            return Err(Error::new(
                variant.span(),
                r#"Missing #[prefix = "..."] attribute"#,
            ));
        }

        let Some(doc_attr) = variant
            .attrs
            .iter()
            .find(|attr| attr.path().is_ident("doc"))
        else {
            return Err(Error::new(variant.span(), "expected a doc comment"));
        };

        let variant_ident = variant.ident;

        if variant_ident != "Ruff" && variant_ident != "Numpy" {
            let (name, url) = parse_doc_attr(doc_attr)?;
            name_match_arms.extend(quote! {Self::#variant_ident => #name,});
            url_match_arms.extend(quote! {Self::#variant_ident => Some(#url),});
        }

        for lit in &prefixes {
            parsed.push((
                lit.clone(),
                variant_ident.clone(),
                match prefixes.len() {
                    1 => ParseStrategy::SinglePrefix,
                    _ => ParseStrategy::MultiplePrefixes,
                },

View on GitHub (pinned to 26f38c119c)

Solutions

Add a doc comment of the form `/// [Linter Name](https://example.com/docs)` directly above the variant.
Keep the comment attached to the variant (no blank line between the doc comment and the variant).
Rebuild so the macro can parse the doc attribute into the name/URL pair.

Example fix

// before
#[prefix = "MYL"]
MyLinter,
// after
/// [MyLinter](https://docs.example.com/mylinter)
#[prefix = "MYL"]
MyLinter,

Defensive patterns

Strategy: validation

Validate before calling

// Pre-commit check that each linter variant is preceded by a /// line:
// if rust code variant has no preceding '///' line -> fail the script.

Prevention

Always write the doc link before the #[prefix] attribute.
Never disable the missing-docs lint for this enum.
Run the build immediately after adding a variant; the macro reports the offending span.

When it happens

Trigger: Declaring a variant on the linter namespace enum with `#[prefix = "..."]` set but no preceding `/// [name](url)` doc comment. Raised at rule_namespace.rs:93 when `attrs.iter().find(|attr| attr.path().is_ident("doc"))` returns None.

Common situations: Adding a new linter variant and writing only the prefix attribute; stripping doc comments via a linter/codemod; suppressing a missing-docs lint that also removed the comment.

Related errors

AI-assisted analysis of astral-sh/ruff@26f38c119c (2026-09-05). Data as JSON: /api/errors/5d9f1623941b89b7. Report an issue: GitHub.