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

Expected doc attribute.

Error message

Expected doc attribute.

What it means

A syn compile error from parse_doc in the ConfigurationOptions derive: an attribute expected to be a doc comment is not a name-value string literal (e.g. it is a list-shaped or non-string attribute). Doc text is extracted only from #[doc = "..."] forms.

Source

Thrown at crates/ruff_macros/src/config.rs:151

                "Expected `Option<_>`  as type.",
            )),
        },
        _ => Err(syn::Error::new(ident.span(), "Expected type.")),
    }
}

/// Parse a `doc` attribute into it a string literal.
fn parse_doc(doc: &Attribute) -> syn::Result<String> {
    match &doc.meta {
        syn::Meta::NameValue(syn::MetaNameValue {
            value:
                syn::Expr::Lit(ExprLit {
                    lit: Lit::Str(lit_str),
                    ..
                }),
            ..
        }) => Ok(lit_str.value()),
        _ => Err(syn::Error::new(doc.span(), "Expected doc attribute.")),
    }
}

/// Parse an `#[option(doc="...", default="...", value_type="...",
/// example="...")]` attribute and return data in the form of an `OptionField`.
fn handle_option(field: &Field, attr: &Attribute) -> syn::Result<proc_macro2::TokenStream> {
    let docs: Vec<&Attribute> = field
        .attrs
        .iter()
        .filter(|attr| attr.path().is_ident("doc"))
        .collect();

    if docs.is_empty() {
        return Err(syn::Error::new(
            field.span(),
            "Missing documentation for field",
        ));
    }

View on GitHub (pinned to 26f38c119c)

Solutions

1. Use standard /// doc comments on the field
2. Remove malformed doc attributes that are not string literals

When it happens

Trigger: Thrown at crates/ruff_macros/src/config.rs:151 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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