Clippy lint · Restriction · checked with Clippy 0.1.99

clippy::definition_in_module_root: Checks for definitions (structs, functions, traits, etc.) in mod.rs files

What it meansChecks for definitions (structs, functions, traits, etc.) in mod.rs files. lib.rs and main.rs are not checked. It is in the restriction group and off by default.

Does it matter?

mod.rs is well-suited to acting as a table of contents , listing submodules and re-exports while leaving definitions to named files. Naming each file after its primary definition keeps filenames descriptive and unique, makes editor tabs and search results easier to scan, and makes the filesystem tree mirror the module tree, so the file layout is uniquely determined by the module structure.

Lints that forbid language features for specific codebases (no unwrap, no indexing...). Off by default; pick them one by one, never the whole group.

How to fix it

Clippy does not fix this one automatically. Change the code by hand:

Flagged

// stuff/mod.rs
mod bar;
pub struct Foo { /* ... */ }
impl Foo { /* ... */ }

Write this instead

// stuff/mod.rs
mod bar;
mod foo;
pub use foo::Foo;

// stuff/foo.rs
pub struct Foo { /* ... */ }
impl Foo { /* ... */ }

Turn it off, or on

It is off by default. To use it, set it to warn or deny:

Whole crate (Cargo.toml)

[lints.clippy]
definition_in_module_root = "warn"

In code

#![warn(clippy::definition_in_module_root)]

One run

cargo clippy -- -W clippy::definition-in-module-root

The [lints] table needs Rust 1.74 or newer. In a workspace, put it under [workspace.lints.clippy] and add [lints] workspace = true to each member.

Restrictiongroup

allowdefault level

nofixed by cargo clippy --fix

1.99.0added in Rust

Clippy's own documentation

What it does

Checks for definitions (structs, functions, traits, etc.) in mod.rs files. lib.rs and main.rs are not checked.

Why restrict this?

mod.rs is well-suited to acting as a table of contents , listing submodules and re-exports while leaving definitions to named files. Naming each file after its primary definition keeps filenames descriptive and unique, makes editor tabs and search results easier to scan, and makes the filesystem tree mirror the module tree, so the file layout is uniquely determined by the module structure.

Example

// stuff/mod.rs
mod bar;
pub struct Foo { /* ... */ }
impl Foo { /* ... */ }

Use instead:

// stuff/mod.rs
mod bar;
mod foo;
pub use foo::Foo;

// stuff/foo.rs
pub struct Foo { /* ... */ }
impl Foo { /* ... */ }

Notes

This lint is most useful alongside self_named_module_files, which requires mod.rs files; together they constrain mod.rs to declarations only. Under mod_module_files (which forbids mod.rs entirely) this lint has nothing to fire on.

If a definition’s name matches its parent module’s name, moving it produces foo/foo.rs, which module_inception flags , projects in that situation typically also allow(module_inception).

From the Clippy lint list (0.1.99), part of the Rust project, MIT or Apache-2.0. Official entry.

Up next

Also worth your time

Did this answer your question?