Document built-in syntax extensions

[brson]

core::unstable::extfmt has some good documentation about fmt! but this module is an implementation detail and isn't (or shouldn't be) shown in the docs. Maybe rustdoc could have a way to write arbitrary pages of documentation and we could have one for syntax extensions and macros. Once syntax extensions become user-definable then we could create a more general way of documenting them.

[Kimundi]

Right, would be nice if macros and syntax extensions would behave more like normal items in that regard. Proposals:

• allow doc attributes on macro-rules! invokations
• rustdoc would then use those to generate docs for macros
• a way to expand/hide item-macros in the docs, so that you can see what those define
• as a temporary way to add documentation: doccomments on a fake_item!(name) item-macro using the same mechanic as the macro-rules one above

[graydon]

For macros I think @Kimundi has the right idea(s). For compiled syntax extensions, I suspect rustdoc should be taught to declaratively associate a syntax extension name with the module defining it. Possibly this could be an additional attribute on the module containing the extension, possibly part of the hypothetical loadable-syntax-extension-defining form, like a #[define_syntax_extension(fmt)]; to go along with a hypothetical #[use_syntax_extension(fmt=libsyntax_fmt)]; or such (as sketched in #6735) ?

[msullivan]

Nothing new to report.

[flaper87]

Visiting for triage. Attributes are now allowed in macros and macros tagged with #[macro_export] will be showed in the documentation.

Still some work left here, though.