document the file! macro

[indirect]

Found out about file! today from o11c in IRC.

[alexcrichton]

Hm, there seem to be a number of things wrong with this section in the documentation. Notable the fmt! macro doesn't exist and the env! macro has undocumented semantics. Additionally, this is missing a lot of macros defined by the compiler.

With bors's queue so full right now, I would rather take the time to fix this properly rather than just inching it forward a little bit.

What do you think about this? I'd almost think that this section should get removed because there's no way for it to stay up to date.

[huonw]

I'd almost think that this section should get removed because there's no way for it to stay up to date.

I disagree, we don't change/remove the functionality of macros that often; we may add things, but leaving only new ones undocumented is better than having everything undocumented.

[indirect]

I think that as Rust settles down heading in to 1.0 it will be even easier to keep the list updated, and I would much rather have imperfect documentation than no documentation. :)

[indirect]

Maybe off-topic, but can't bors merge documentation without having to build everything on every platform? If not, that seems like a really big obstacle for documenting rust in the official docs rather than other github repos that can easily accept patches.

[huonw]

We test examples in documentation to make sure they are compilable.

(I know this one doesn't touch any examples, but running everything through the bots helps reduce the chance of a mistake on the part of the reviewer.)

[olsonjeffery]

Dovetailing on the "We test examples in documentation" thing, I'd love to set up a stub module in libstd that just contains documentation and examples for the various compiler macros. I think we can do better than a bullet-point list in the reference manual.

[olsonjeffery]

(and yes, I'm offering to do the work in another PR, provided there's buy-in that this is a tenable approach)

[indirect]

@huonw how is that possible given e.g. #11693?

@olsonjeffery I was thinking of just expanding the Macro section in the manual to include sections and documentation for each macro, actual API documentation sounds better to me for sure.

[huonw]

@indirect as Alex says on that PR, it's correct on master.