Specify the behavior of file! by epage · Pull Request #134442 · rust-lang/rust (original) (raw)

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).