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!