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

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.

Open the std::include! documentation at the linked URL and compare it with the module/file.rs example in the issue. Verify the demonstrated module-resolution behavior, then document how mod is resolved relative to included code and clarify how this differs from literal pasting; the documentation should explain the failing example without requiring the proposed macro design.