Allow documentation to be read from an external file

[huonw]

I.e. the following are equivalent:

lib.rs

//! Foo bar baz

---

lib.rs

#![doc(file = "extensive_crate_docs.md")]

extensive_crate_docs.md:

Foo bar baz

This could be used in the rust source for modules like borrowck::doc: having that as a separate .../borrowck/doc.md file with #[doc(file="doc.md")] mod doc {} in .../borrowck/mod.rs might be nice (it would certainly make editing it more natural, as editors will automatically select the Markdown mode).

[huonw]

Depending how this is handled, it may get in the way of #2206 (i.e. it would probably be good to handle it so that #2206 can still work).

[tomjakubowski]

I have a proof of concept, out of tree implementation here: https://github.com/tomjakubowski/doc_file

[steveklabnik]

Triage: rust-lang/cargo#739 is related, but not the same.

[euclio]

What's the status on this? Does it need an RFC or are we waiting on an in-tree implementation?

[QuietMisdreavus]

This is an RFC now: rust-lang/rfcs#1990

Discussion on it is fairly positive, so it's likely that something to this effect is going to happen.