oxc-project/oxc · error · syn::Error

rule documentation must be specified either via doc comments

Error message

rule documentation must be specified either via doc comments or the `docs` attribute

What it means

Compile-time error raised inside the declare_oxc_lint! proc-macro when no rule documentation was provided — neither doc comments (///) on the declaration nor a docs attribute. Every published rule must carry rendered documentation, so the macro rejects the expansion.

Source

Thrown at crates/oxc_macros/src/declare_oxc_lint.rs:218

        let Some(version) = version else {
            return Err(Error::new(
                struct_name.span(),
                "missing `version = \"x.y.z\"` or `version = \"next\"` in `declare_oxc_lint!`",
            ));
        };

        // Validate that any markdown fenced code blocks (```) in rule docs are properly closed.
        // If the total number of fences found is odd, a block was not closed.
        #[cfg(feature = "ruledocs")]
        if !backtick_fences_count.is_multiple_of(2) {
            return Err(Error::new(
                struct_name.span(),
                "unclosed markdown code block in documentation, please close all ``` fences",
            ));
        }
        #[cfg(feature = "ruledocs")]
        let Some(documentation) = documentation else {
            return Err(Error::new(
                struct_name.span(),
                "rule documentation must be specified either via doc comments or the `docs` attribute",
            ));
        };

        Ok(Self {
            name: struct_name,
            is_tsgolint_rule,
            plugin,
            category,
            fix,
            #[cfg(feature = "ruledocs")]
            documentation,
            used_in_test: false,
            config,
            version,
            #[cfg(feature = "ruledocs")]
            short_description,

View on GitHub (pinned to a3d33dda7c)

Solutions

1. Add /// doc comments describing what the rule does and why
2. Or supply the documentation via the docs attribute in the declare_oxc_lint! block

When it happens

Trigger: Thrown at crates/oxc_macros/src/declare_oxc_lint.rs:198 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of oxc-project/oxc@a3d33dda7c (2026-08-20). Data as JSON: /api/errors/a7d9a8a0545193f9. Report an issue: GitHub.