Allow doc-strings on item macros

[eholk]

Some of our libraries are starting to export protocols. It'd be nice to be able to add documentation to these that gets included in the Rustdocs.

I don't know if it's better to document it as a macro invocation, or as documentation on whatever the macro expands to. For protocols, both makes sense, although documenting the unexpanded version is probably more useful to the user.

[catamorphism]

far-future

[bblum]

Also useful for conditions, now that protocols have been put on indefinite ice.

[emberian]

Macros are no longer present in the AST (are they ever present? I see an item_mac) when rustdoc_ng visits it.

/cc @jbclements @paulstansifer

[paulstansifer]

@cmr They are expanded away by macro expansion... should rustdoc_ng expand macros? I'm afraid that the answer might be complicated.

[emberian]

@paulstansifer rustdoc_ng expands macros because there are modules that need documenting that are generated by macros (specifically std::f32 etc)

[paulstansifer]

@cmr That makes sense. In theory, it could also make sense to have only documentation for all of the generated modules as a whole (after all, the text will always be the same)... but cross-referencing and various edge cases might make that very tricky.

[emberian]

@paulstansifer Could I parse, pull out the item_mac's, and then continue with the rest of the compilation pipeline? Since they are purely disjoint from the final AST I get I don't see any problems with it.

[paulstansifer]

@cmr I don't see any reason why that couldn't work.