`include!` docs don't explain how `mod` is resolved

[StanleyRoberts]

Location (URL)

https://doc.rust-lang.org/std/macro.include.html

Summary

The include! macro appears to resolve modules before being 'pasted' into the current file. E.g. The following crate fails to compile

/
├── module/
│   └── file.rs
├── module.rs
├── include/
│   └── include_src.rs
└── lib.rs

with file.rs:

pub fn foo() { todo!() }

include_src.rs:

mod file;

fn bar() { file::foo() }

and module.rs:

include!("include/include_src.rs");

The include! macro documentation does not mention this behaviour.

As an aside:
This behaviour is very unintuitive to me, I expected include! to behave exactly like pasting the included code into the current file.
This also makes writing build scripts whose outputs contain mod problematic. In my project, include_src.rs is an output of a build script; I've had to replace the mods with mod file { include!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/module/file.rs")); } which isn't ideal and also seems to disable r-a's Intellisense for file.rs.
It would be useful to have a macro that does not do any sort of parsing/resolution to allow this pattern.

[lolbinarycat]

This definitely should be specified in the docs, but also note you can use the #[path] attribute to manually override what filepath is read for a particular module.

[StanleyRoberts]

@lolbinarycat Thanks for pointing me to #[path], that lets me do what I wantes.
Regarding the documentation, is this something I can just open a PR for?

[ehuss]

There some more context about this in https://github.com/rust-lang/rust/pull/69838/files#r395217057 and #70184.