This seems confusing. You mean in the "child" module in question? Isn't that just, necessarily, the source path "passed to the Rust compiler"?

It seems like it's trying to mention this example as if it's an exception, when in reality "finding the path to an out-of-line module" is always a "path operation".

This made sense to me as written. The filepath passed to the Rust compiler is always only the path of the root module. In every other module, the value of file! is the result of a sequence of well-specifiable path operations performed on the root module's path.

For example in rustc path/to/root.rs containing a #[path = "some/where.rs"] module, file! in the submodule would be "path/to/some/where.rs".

This paragraph is indicating that "path/to/some/where.rs" is derived from (sensitive to) 2 things:

1. The root module's source path as passed to the Rust compiler. So if you had run rustc /absolute/path/to/root.rs instead, or rustc ./wat/../path/to/root.rs, you should expect that the submodule's file! would be different, even though neither the root module nor child module has changed location in the filesystem. Ed's documentation is pointing out the important fact that the path passed to the compiler is relevant.

2. The sequence through which we arrive from the root module to the module containing the file! call site, whether that's mod or #[path = …] or include!(…). If you change that, you should expect that file! can return something different in the child module.

From your comment, it is not clear to me what possible unintended interpretation of the documentation is taking place. Is it about whether #[path = "<child>"] constitutes a "path passed to the Rust compiler"? (It does not. The path passed to the Rust compiler refers to a command-line argument.)

If it's confusing to an expert, then perhaps we might benefit by saying more or saying it differently. In fact, much of what you wrote by way of explanation could itself make sense in the documentation.

1. #[path] usually is an exceptional case (because it is designed to allow exceptional cases). mentioning an exceptional case without describing the normal case can mislead people in a number of directions. this includes the situation when the exceptional case is functionally identical to the normal case.
2. "what operations the compiler performs on filesystem paths such that I can understand what file! will give the name of" is not really addressed by the documentation at hand. it seems about 200 additional words was needed to describe what those are?
3. the purpose of our public-facing API documentation is to be useful to people who are not familiar with the vagaries of the matter at hand.
4. we already have documentation that better describes the way files are discovered on the filesystem, and are probably better served by relating things back to it and expanding it if necessary: https://doc.rust-lang.org/reference/items/modules.html#module-source-filenames
5. @dtolnay you seem to have noticed that remarks that are overly terse are hard to interpret. are you sure you were correct in interpreting "This seems confusing" as "I am confused"?

Yes, if it was confusing, let's improve it. However, I don't see dtolnay's comments saying we shouldn't but providing an anchor for the conversation to find what aspect was confusing (and it was nice to get confirmation that I wasn't so far off the mark as a contributor). Thats important for understanding how to fix it. I find it helpful because I'm not fully clear on what the initial feedback is (it makes it sound like I'm saying <child> is the root source module?).

So going off of the more specific points and with dtolnay's wording, I've made some tweaks. I hope they helped. In giving feedback, please help me understand why it seems confusing so we can discuss points on it.

I chose #[path] because I felt it was simpler to provide an example (mod file vs non-mod, directory vs file mod, etc) but has some confusing parts as well (still conditioned on mod-file vs non-mod. I found making the example more concrete can bypass those cases and switched to using mod foo;.

I hadn't thought of delegating to the reference but in looking at the reference, I worry that doing so would also be confusing because its framed around answering a different question (the module system) with assumptions like paths are relative to the source module's directory. I could see possibly linking to it for more details.

Something I want to be cautious about is distracting from the core messages of this documentation. The core point of file! is whats currently documented. The core message of this new documentation is the base directory for relative paths while the rest is context to understand it and the limitations (maybe I'm being biased by my workflows).

...or ./src/foo/mod.rs :) Perhaps something like:

Since there is a complete sentence before this, I think the parentheses could be removed and "e.g." replaced with "For example,".

As-is this parenthetical clause starts a sentence and then is followed by , modified by any..., I think that trailer is meant to go with the first sentence (before this example) in either case.

Agreed. The full stop ahead of the parenthetical seems an error, as the sentence does continue after the parenthetical. As you say, probably it'd be better to keep the sentence together and state the "For example" after it.

I pulled the example out into a sentence at the end so that the longer example doesn't break the flow of the explanation.

I am just a daily rust user, not a compiler expert but I have used file macro before and I think this sentence is relatively hard to grasp. I think an example could help.

I understood it as follows: If file!() is called from another macro, then it returns the name of the file where the outer macro is called, not the file where the literal file!() invocation is.

If that's correct, the original description is clear to me.

Sorry if it looked like I was implying the documentation was wrong. That was not my intention, I was just asking for an example because it usually helps to understand things. If y'all think it's clear enough, feel free to resolve that thread.

While it can be useful to find ways to improve documentation, this is out of scope of this PR. This was only called out because I didn't pay enough attention when I re-wrapped the lines and my editor and the author of this section's disagreed on the line wraps. I have since reverted that change.