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

expected doc comment to be in the form of `/// [name](https:

Error message

expected doc comment to be in the form of `/// [name](https://example.com/)`

What it means

The rule-namespace derive macro requires each linter variant's doc comment to be a markdown link of the exact form `[name](url)`, from which it extracts the linter's display name and documentation URL. `parse_doc_attr` returns this error when the doc string exists and is well-formed as an attribute but its content does not parse as a markdown link.

Source

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

fn parse_doc_attr(doc_attr: &Attribute) -> syn::Result<(String, String)> {
    let Meta::NameValue(MetaNameValue {
        value:
            syn::Expr::Lit(ExprLit {
                lit: Lit::Str(doc_lit),
                ..
            }),
        ..
    }) = &doc_attr.meta
    else {
        return Err(Error::new(
            doc_attr.span(),
            r#"expected doc attribute to be in the form of #[doc = "..."]"#,
        ));
    };
    parse_markdown_link(doc_lit.value().trim())
        .map(|(name, url)| (name.to_string(), url.to_string()))
        .ok_or_else(|| {
            Error::new(
                doc_lit.span(),
                "expected doc comment to be in the form of \
                `/// [name](https://example.com/)`",
            )
        })
}

fn parse_markdown_link(link: &str) -> Option<(&str, &str)> {
    link.strip_prefix('[')?.strip_suffix(')')?.split_once("](")
}

enum ParseStrategy {
    SinglePrefix,
    MultiplePrefixes,
}

View on GitHub (pinned to 26f38c119c)

Solutions

1. Rewrite the doc comment as `/// [Display Name](https://absolute-url)` with an https URL.
2. Verify there is no extra prose before or after the link inside the doc comment.
3. Rebuild to confirm the name/URL pair now parses.

Example fix

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

// Validate locally that the doc comment parses as a markdown link:
// /^(\[[^\]]+\])\((https?:\/\/[^\s)]+)\)$/ matching the trimmed doc text.

When it happens

Trigger: A variant's doc comment contains free text instead of a link, e.g. `/// My linter docs`, or a malformed link like `[name](not-a-url)`. Raised in `parse_doc_attr` (rule_namespace.rs:182) when `parse_markdown_link` returns None.

Common situations: Contributing a new linter and writing a descriptive comment instead of the required link; editing the doc comment for readability and breaking the `[text](https://...)` shape; using a relative URL instead of an absolute https URL.

Related errors

• Missing #[prefix = "..."] attribute
• expected a doc comment
• expected doc attribute to be in the form of #[doc = "..."]
• Expected to handle named fields
• Expected to handle named fields

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