Organize Modules

Module Organization Best Practices

When to Use

• Creating new Rust modules
• Refactoring module structure
• Organizing mod.rs files
• Reviewing code that exposes internal structure
• Making private types visible to documentation
• Before creating commits with module changes
• When user says "organize modules", "refactor modules", "fix module structure", etc.

Instructions

Follow these patterns for clean, maintainable module organization:

Step 1: Apply the Recommended Pattern

Prefer private modules with public re-exports (also known as the barrel export pattern) as the default pattern.

This provides a clean API while maintaining flexibility to refactor internal structure.

// mod.rs - Module coordinator

// Private modules (hide internal structure)
mod constants;
mod types;
mod helpers;

// Public re-exports (expose stable API)
pub use constants::*;
pub use types::*;
pub use helpers::*;

What this achieves:

• Clean, flat API for users
• Internal structure is hidden and can be refactored freely
• No namespace pollution from module names

Step 2: Control Rustfmt Behavior (When Needed)

For mod.rs files with deliberate manual alignment, prevent rustfmt from reformatting:

// mod.rs

#![rustfmt::skip]

// Private modules
mod constants;
mod types;
mod helpers;

// Public re-exports
pub use constants::*;
pub use types::*;
pub use helpers::*;

When to use rustfmt skip:

• Large mod.rs files with many exports
• Deliberately structured code alignment for clarity
• Manual grouping of related items (e.g., test fixtures)
• Files where organization conveys semantic meaning

When NOT to use:

• Small, simple mod.rs files
• When automatic formatting is preferred

Step 3: Apply Conditional Visibility for Docs and Tests

When you need a module to be:

• Private in production builds (encapsulation)
• Public for documentation (rustdoc links work)
• Public for tests (test code can access internals)

Use conditional compilation:

// mod.rs - Conditional visibility

#[cfg(any(test, doc))]
pub mod internal_parser;
#[cfg(not(any(test, doc)))]
mod internal_parser;

// Re-export items for the flat public API
pub use internal_parser::*;

How this works:

• In doc builds: Module is public → rustdoc can see and link to it
• In test builds: Module is public → tests can access internals
• In production builds: Module is private → internal implementation detail

This pattern is frequently used with the write-documentation skill when fixing documentation links to private types.

When to Omit the Fallback Branch

You can skip the #[cfg(not(any(test, doc)))] fallback when the module has no code to compile in production:

// ✅ OK to skip fallback - documentation-only module (no actual code)
#[cfg(any(test, doc))]
pub mod integration_tests_docs;

// ✅ OK to skip fallback - all submodules are #[cfg(test)] anyway
#[cfg(any(test, doc))]
pub mod integration_tests;

Keep the fallback when the module contains code that must compile in production (even if private):

// ✅ Need fallback - module has actual code used in production
#[cfg(any(test, doc))]
pub mod internal_parser;
#[cfg(not(any(test, doc)))]
mod internal_parser;

pub use internal_parser::*;  // Re-exports need the module to exist!

Integration Tests Module

For modules that contain PTY integration tests (typically under integration_tests/), follow these rules:

1. Dedicated Files: Each complex test gets its own file.
2. Module Documentation: Use //! at the top of the file to document the test's intent.
3. Run Instructions: Always include a "Run with:" section at the top of the file (see write-documentation skill for details).
4. Conditional Visibility: Parent modules must make these test modules public for doc and test builds.

// integration_tests/mod.rs

#[cfg(any(test, doc))]
pub mod pty_feature_test;

Platform-Specific Modules with Cross-Platform Docs

For modules that are platform-specific but should have docs generated on all platforms, use any(doc, ...) to separate documentation from runtime requirements:

// ✅ Linux-only runtime, but docs build on all platforms
#[cfg(any(doc, all(target_os = "linux", test)))]
pub mod input;
#[cfg(all(target_os = "linux", not(any(test, doc))))]
mod input;

// Re-export also needs the doc condition
#[cfg(any(target_os = "linux", doc))]
pub use input::*;

Key insight: rustdoc runs the Rust compiler internally. When you write #[cfg(all(target_os = "linux", any(test, doc)))], the target_os = "linux" check still excludes macOS/Windows even during doc builds. The doc cfg flag doesn't override other conditions: it's just another flag you can check.

The fix: Use any(doc, ...) to make doc an alternative path:

• any(doc, all(target_os = "linux", test)) means: "docs on any platform OR tests on Linux"
• all(target_os = "linux", any(test, doc)) means: "Linux AND (tests OR docs)": still requires Linux!

When you see broken doc links for platform-specific modules:

// ❌ Broken: Docs won't generate on macOS
#[cfg(all(target_os = "linux", any(test, doc)))]
pub mod linux_only_module;

// ✅ Fixed: Docs generate on all platforms (if module code is platform-agnostic)
#[cfg(any(doc, all(target_os = "linux", test)))]
pub mod linux_only_module;
#[cfg(all(target_os = "linux", not(any(test, doc))))]
mod linux_only_module;

⚠️ Unix Dependency Caveat

The cfg(any(doc, ...)) pattern above assumes the module's code compiles on all platforms. When the module uses Unix-only APIs (e.g., mio::unix::SourceFd, signal_hook, std::os::fd::AsRawFd), restrict doc builds to Unix:

// Module uses Unix-only APIs: restrict doc builds to Unix platforms
#[cfg(any(all(unix, doc), all(target_os = "linux", test)))]
pub mod input;
#[cfg(all(target_os = "linux", not(any(test, doc))))]
mod input;

#[cfg(any(target_os = "linux", all(unix, doc)))]
pub use input::*;

Three-tier hierarchy:

Rule of thumb: Match your doc cfg guard to your dependency's cfg guard in Cargo.toml.

Apply at all levels: If the module is nested, both parent and child need the visibility change. Also update any re-exports:

// Parent module
#[cfg(any(doc, all(target_os = "linux", test)))]
pub mod integration_tests;

// Child modules inside integration_tests/mod.rs
#[cfg(any(doc, all(target_os = "linux", test)))]
pub mod pty_input_test;

// Re-exports
#[cfg(any(target_os = "linux", doc))]
pub use integration_tests::*;

Step 4: Handle Transitive Visibility

Important: If a conditionally public module links to another module in its documentation, that target module must also be conditionally public.

// mod.rs

#[cfg(any(test, doc))]
pub mod paint_impl;  // Contains docs that link to diff_chunks
#[cfg(not(any(test, doc)))]
mod paint_impl;

#[cfg(any(test, doc))]
pub mod diff_chunks;  // Must also be conditionally public!
#[cfg(not(any(test, doc)))]
mod diff_chunks;

// Re-export for public API
pub use paint_impl::*;
pub use diff_chunks::*;

Why: Rustdoc needs to resolve all links in documentation. If paint_impl docs link to diff_chunks, rustdoc must be able to see diff_chunks.

Step 5: Reference in Rustdoc

When linking to conditionally public modules in documentation, use the mod@ prefix:

/// See [`internal_parser`] for implementation details.
///
/// [`internal_parser`]: mod@crate::internal_parser

See the write-documentation skill for complete details on rustdoc links.

Step 6: Multi-Level Barrel Exports and Rustdoc Search

When rustdoc generates documentation, the search index includes all public items and modules. For multi-level barrel exports (pub mod intermediate; pub use intermediate::*;), the search index resolves the "shortest public path" for items. But rustdoc only generates HTML pages at the canonical definition path, not at the flattened re-export path.

This means searching for an item re-exported via a barrel might produce a link to a page that doesn't exist (e.g., core/ansi/csi/index.html instead of core/ansi/constants/csi/index.html).

The fix: Use #[doc(inline)] to re-export submodules at the parent level, but only when the intermediate module is a well-documented organizational hub (has module-level //! docs, organization tables, etc.) AND its submodules are pub mod.

In the parent module's mod.rs, add explicit #[doc(inline)] re-exports alongside the existing glob re-export:

// Existing: keeps flat item access working
pub use constants::*;

// New: creates rustdoc pages at the parent path for searchability
#[doc(inline)] // Create doc pages at re-export path so rustdoc search links resolve.
pub use constants::{csi, dsr};

Always include the inline comment on #[doc(inline)] lines:

#[doc(inline)] // Create doc pages at re-export path so rustdoc search links resolve.

If the re-exported modules use conditional visibility (#[cfg(any(test, doc))]), add the guard with its own inline comment:

#[cfg(any(test, doc))] // Guard needed: constants sub-modules are only pub in doc/test builds.
#[doc(inline)] // Create doc pages at re-export path so rustdoc search links resolve.
pub use constants::{csi, dsr};

This creates pages at both paths (ansi/csi/ AND ansi/constants/csi/), so rustdoc search links work regardless of which path the search index resolves.

Step 7: Macro Module Organization

For modules that define #[macro_export] macros, do NOT use #[macro_use] on module declarations. Instead, use explicit imports at call sites:

// mod.rs - Do NOT use #[macro_use]
pub mod macros;  // ✅ Just declare the module

// At each call site that uses the macro:
use crate::my_macro;  // ✅ Explicit import
my_macro!();

Why: #[macro_use] is a Rust 2015 pattern that depends on module declaration order and breaks silently when modules are reordered. #[macro_export] macros are available at the crate root in Rust 2018+, so use crate::macro_name; works everywhere.

Inner modules: use crate::macro_name; imports do NOT propagate into child mod blocks. Each inner module that uses a macro needs its own import:

use crate::ok;  // Available in this file's scope

mod inner {
    use crate::ok;  // Must import separately - parent scope doesn't propagate
    fn example() { ok!() }
}

Test-only macros: Guard imports with #[cfg(test)] to avoid unused import warnings:

#[cfg(test)]
use crate::assert_eq2;

Benefits of This Pattern

1. Clean, Flat API

Users import directly without unnecessary nesting:

✅ Good (flat, ergonomic):

use my_module::MyType;
use my_module::CONSTANT;

❌ Bad (exposes internal structure):

use my_module::types::MyType;
use my_module::constants::CONSTANT;

2. Refactoring Freedom

Internal reorganization doesn't break external code:

// You can move items between files freely
// External API stays: use my_module::Item;

// Before:
// mod.rs: pub use types::Item;
// types.rs: pub struct Item;

// After refactoring:
// mod.rs: pub use helpers::Item;  // Changed!
// helpers.rs: pub struct Item;    // Moved!

// External code unaffected:
// use my_module::Item;  // Still works!

3. Avoid Naming Conflicts

Private module names don't pollute the namespace:

// No conflicts with other `constants` modules in the crate
mod constants;  // Private - name hidden
pub use constants::*;  // Items public

// Elsewhere in the crate
mod constants;  // No conflict! This is in a different scope

⚠️ Warning: Re-export Collisions with pub mod

While private module names don't collide, their public contents (including public submodules) will collide if they share the same name and are pulled into the same parent namespace via glob re-exports (pub use module::*;).

If multiple modules in the same hierarchy have submodules with identical names (e.g., several pub mod integration_tests;), glob re-exporting them into a single parent module will cause ambiguous re-export errors, because the module names leak into the public API.

How to solve test module collisions:

1. The Default: Make test modules private (mod integration_tests;). They do not need to be pub for cargo test to find them. This perfectly encapsulates the module, preventing namespace pollution and collisions.
2. The Rustdoc Exception: If you must link to a test module in your documentation using intra-doc links, it must be pub mod. In this case, you must use a uniquely prefixed name (e.g., pub mod vt_100_parser_integration_tests; instead of integration_tests) to prevent it from colliding with other public test modules in the global namespace.

4. Encapsulation

Module structure is an implementation detail, not part of the API:

// Internal structure can change without breaking compatibility
// v1.0: mod types; pub use types::*;
// v1.1: mod models; pub use models::*;  // Renamed module
// Users don't care!

Decision Trees

When to Use Private Modules + Public Re-exports

✅ Use this pattern when:

• Module structure is an implementation detail
• You want a flat, ergonomic API surface
• Avoiding potential name collisions across the crate
• Working with small to medium-sized modules with clear responsibilities
• Building a library with a stable public API

Example scenarios:

• Utility modules with helpers, types, constants
• Internal parser implementation
• Data structure implementations

When NOT to Use This Pattern

❌ Keep modules public when:

1. Module Structure IS the API

Different domains should be explicit:

pub mod frontend;  // Frontend-specific APIs
pub mod backend;   // Backend-specific APIs

// Users: use my_crate::frontend::Component;
// Users: use my_crate::backend::Database;

Why: The separation is meaningful to users. They WANT to know if they're using frontend or backend APIs.

2. Large Feature Domains

When namespacing provides clarity for 100+ items:

pub mod graphics;   // 100+ graphics-related items
pub mod audio;      // 100+ audio-related items
pub mod physics;    // 100+ physics-related items

// Users: use engine::graphics::Renderer;
// Users: use engine::audio::Mixer;

Why: Flat re-export of 300+ items would be overwhelming. Namespacing aids discovery.

3. Optional/Conditional Features

Make feature boundaries explicit:

#[cfg(feature = "async")]
pub mod async_api;  // Keep separate for clarity

#[cfg(feature = "serde")]
pub mod serialization;

// Users: use my_crate::async_api::Client;

Why: Users need to know which features enable which APIs.

Inner Modules vs. Separate Files

When organizing code into logical groups, choose between inner modules (same file) and separate files based on file size and complexity.

Inner Modules (Same File)

✅ Use inner modules when:

• File is small-to-medium (under ~300 lines total)
• Groups are logically related and benefit from proximity
• Comment banners (// ======) are being used to separate sections
• Each group is relatively small (~20-50 lines)

// ansi_sequence_generator.rs - Inner module pattern

pub struct AnsiSequenceGenerator;

mod cursor_movement {
    use super::*;
    impl AnsiSequenceGenerator {
        pub fn cursor_position(...) -> String { ... }
        pub fn cursor_to_column(...) -> String { ... }
    }
}

mod screen_clearing {
    use super::*;
    impl AnsiSequenceGenerator {
        pub fn clear_screen() -> String { ... }
        pub fn clear_current_line() -> String { ... }
    }
}

mod color_ops {
    use super::*;
    impl AnsiSequenceGenerator {
        pub fn fg_color(...) -> String { ... }
        pub fn bg_color(...) -> String { ... }
    }
}

Benefits:

• Single-file cohesion - everything related stays together
• Easier navigation - no jumping between files
• Clear grouping - mod keyword is more formal than comment banners
• Scoped imports - each inner mod can import only what it needs

Separate Files

✅ Use separate files when:

• Individual groups exceed ~100 lines each
• Groups have distinct dependencies (different imports)
• File would exceed ~500 lines total
• Groups are conceptually independent (could be tested separately)

generator/
├── mod.rs                    # Re-exports + struct definition
├── cursor_movement.rs        # impl AnsiSequenceGenerator { cursor_* }
├── screen_clearing.rs        # impl AnsiSequenceGenerator { clear_* }
├── color_ops.rs              # impl AnsiSequenceGenerator { colors }
└── terminal_modes.rs         # impl AnsiSequenceGenerator { modes }

Code Smell: Comment Banners

If you find yourself writing comment banners like this:

impl MyStruct {
    // ==================== Group A ====================
    fn method_a1() { ... }
    fn method_a2() { ... }

    // ==================== Group B ====================
    fn method_b1() { ... }
    fn method_b2() { ... }
}

This is a signal to formalize the grouping using either inner modules (small file) or separate files (large file). Comment banners are informal and don't provide the same benefits as actual module boundaries (scoped imports, clear boundaries, IDE navigation).

Complete Examples

Example 1: Simple Module Organization

// src/terminal/mod.rs

#![rustfmt::skip]

// Core types
mod position;
mod size;
mod style;

// State management
mod cursor;
mod buffer;

// Public API - flat exports
pub use position::*;
pub use size::*;
pub use style::*;
pub use cursor::*;
pub use buffer::*;

Usage:

use terminal::{Position, Size, Style, Cursor, Buffer};
// Not: use terminal::position::Position;

Example 2: Conditional Visibility for Docs

// src/parser/mod.rs

// Make internal modules public for docs and tests
#[cfg(any(test, doc))]
pub mod vt_100;
#[cfg(not(any(test, doc)))]
mod vt_100;

#[cfg(any(test, doc))]
pub mod escape_sequences;
#[cfg(not(any(test, doc)))]
mod escape_sequences;

// Public API
pub use vt_100::*;
pub use escape_sequences::*;

Now rustdoc can link to these modules:

/// Uses [`vt_100`] for parsing.
///
/// [`vt_100`]: mod@crate::parser::vt_100

Example 3: Mixed Public and Private Modules

// src/rendering/mod.rs

// Public modules (API namespacing)
pub mod backends;     // Different backend implementations
pub mod widgets;      // UI widgets

// Private modules (internal implementation)
mod buffer;
mod diff_engine;

// Selective re-exports
pub use buffer::RenderBuffer;  // This one is public
// diff_engine stays internal

Usage:

use rendering::backends::Crossterm;
use rendering::widgets::Button;
use rendering::RenderBuffer;  // Flat re-export
// Cannot use: rendering::diff_engine  // Private!

Common Mistakes

❌ Mistake 1: Everything Public

// mod.rs - Bad!
pub mod constants;
pub mod types;
pub mod helpers;

Problem: Exposes internal structure, hard to refactor later.

❌ Mistake 2: Forgetting Transitive Visibility

// mod.rs - Bad!
#[cfg(any(test, doc))]
pub mod a;  // Docs link to module b

mod b;  // Private! Rustdoc can't see it

Problem: Rustdoc can't resolve links from a to b.

Fix:

#[cfg(any(test, doc))]
pub mod a;

#[cfg(any(test, doc))]
pub mod b;  // Also conditionally public
#[cfg(not(any(test, doc)))]
mod b;

❌ Mistake 3: Using Conditional Visibility Everywhere

// mod.rs - Overkill!
#[cfg(any(test, doc))]
pub mod utils;
#[cfg(not(any(test, doc)))]
mod utils;

Problem: Only use conditional visibility when:

• Linking to the module in rustdoc, OR
• Accessing the module from test code

Simple case: If module items are re-exported and you don't need to link to the module itself, just use private modules.

Reporting Results

After organizing modules:

• ✅ Organized successfully → "Module structure organized with private modules and public re-exports!"
• 🔧 Made conditionally public → Report which modules got conditional visibility
• 📝 Manual review needed → List modules that may need public exposure for API reasons

Supporting Files in This Skill

This skill includes additional reference material:

• examples.md - 6 complete, working examples of module organization for different scenarios: simple library with internal structure, conditional visibility for documentation, large crate with domain separation, test-only module visibility, gradual refactoring strategy, and avoiding naming conflicts. Each example shows full file structure and implementation. Read this when:
  • Simple library module organization → Example 1
  • Need conditional visibility for docs/tests → Example 2
  • Large crate with multiple domains (graphics/audio/physics) → Example 3
  • Test utilities that should only exist in test builds → Example 4
  • Refactoring from public modules to private + re-exports → Example 5
  • Avoiding module naming conflicts → Example 6
  • Decision tree for when to use which pattern → End of file

Related Skills

• write-documentation - For documenting module organization and fixing intra-doc links (uses conditional visibility for linking private types)
• run-clippy - Ensures mod.rs follows patterns

Related Commands

No dedicated command, but used by:

• /clippy - Checks module organization as part of code quality
• /fix-intradoc-links - Uses conditional visibility patterns from this skill

Related Agents

• clippy-runner - Invokes this skill to enforce module patterns