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

Missing documentation for field

Error message

Missing documentation for field

What it means

A syn compile error from handle_option in the ConfigurationOptions derive: the field has no #[doc ...] attributes at all. Every option field must carry documentation because it feeds the generated settings reference.

Source

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

                    ..
                }),
            ..
        }) => 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",
        ));
    }

    // Convert the list of `doc` attributes into a single string.
    let doc = dedent(
        &docs
            .into_iter()
            .map(parse_doc)
            .collect::<syn::Result<Vec<_>>>()?
            .join("\n"),
    )
    .trim_matches('\n')
    .to_string();

    let ident = field
        .ident

View on GitHub (pinned to 26f38c119c)

Solutions

1. Add a /// doc comment describing the option
2. Run cargo dev generate-all after documenting to regenerate docs

When it happens

Trigger: Thrown at crates/ruff_macros/src/config.rs:165 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/9633fce5e743f179. Report an issue: GitHub.