Modules defined by combining multiple files.

[crlf0710]

Define a proc macro that collects and combines multiple sources into a single module.

// lib.rs

#[paths("a.rs", "b.rs")]
mod foo;

// a.rs
//! inner docstring comment 1
struct Part1;

// b.rs
//! inner docstring comment 2

struct Part2;

got expanded into (with proper Spans if possible):

// lib.rs
mod foo {
    //! inner docstring comment 1
    //! inner docstring comment 2

    struct Part1;
    struct Part2;
}

[CreepySkeleton]

What it would be useful for?

[dtolnay]

I think any implementation of this would destroy all the spans, so I am skeptical that a macro would be worthwhile.

[dtolnay]

A workaround would be to write:

mod foo {
    //! inner docstring comment 1
    //! inner docstring comment 2

    mod a;
    mod b;

    pub use a::*;
    pub use b::*;
}

[crlf0710]

that's a little different, with the current visibility rules, some arrangement needs to be done in a.rs and b.rs to make them work together. (Additional uses, for example.) But it will mostly work.

Too bad Span referring to external files cannot be created. I left a ticket in rust-lang/rfcs#2869 .