libcore documentation for builtin macros

[newpavlov]

Fixes: #36272

Additionally I've edited docstring for include! a bit. (related PR #36404)

Unfortunately it seems there is no sane way to reexport empty macros definitions for their docstrings. To avoid copying the whole documentation for builtin macros I've only copied description and added links to std macro pages.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @aturon (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[steveklabnik]

@bors: delegate=frewsxcv

[bors]

✌️ @frewsxcv can now approve this pull request

[frewsxcv]

Is it not possible to move the macros currently in std from std to core and add them to this attribute?

[newpavlov]

I mentioned it in the OP. Naively moving mod builtin to libcore and adding reexports will result in reexported macro not found error. I've tried to play around with #[cfg_attr(dox, macro_reexport(...))] but without any results.

I am unable to fully analyze why this error happens, but my guess is what when we trying to compile docs and use extern crate core we compile libcore without dox option. Probably it can be fixed by modification of makefile or by using some another way, but it will require more in-depth knowledge which I do not currently posses.

[newpavlov]

If you want to try to fix reexported macro not found error you can look at this branch.

[frewsxcv]

Thanks!

@bors r+ rollup

[bors]

📌 Commit 34576da has been approved by frewsxcv

[bors]

⌛ Testing commit 34576da with merge 87af232...

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-cargotest, auto-linux-64-cross-freebsd, auto-linux-64-debug-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-opt-rustbuild, auto-linux-64-x-android-t, auto-linux-cross-opt, auto-linux-musl-64-opt, auto-mac-32-opt, auto-mac-64-opt, auto-mac-64-opt-rustbuild, auto-mac-cross-ios-opt, auto-win-gnu-32-opt, auto-win-gnu-32-opt-rustbuild, auto-win-gnu-64-opt, auto-win-msvc-32-opt, auto-win-msvc-64-cargotest, auto-win-msvc-64-opt, auto-win-msvc-64-opt-rustbuild
Approved by: frewsxcv
Pushing 87af232 to master...

[eddyb]

Sadly this broke cross-crate [src] links in rustdoc (which is already a crumbling pile of hacks).
What's happening is that this introduces exactly one new item (the mod) which is not present when libcore is build regularly, and that determines what DefIds compiling libstd sees.
The difference of 1 in the DefId (or rather, DefIndex) between documented libcore and imported-by-libstd libcore shows up in the cross-crate [src] links, which assumes identical libcores.

Simplest fix would be to just remove the mod and apply the #[cfg(dox)] to each macro instead.
cc @rust-lang/tools

[newpavlov]

@eddyb
So I need to remove mod builtin from libcore and instead use #[cfg(dox)] on each builtin macros, is it right? Should I create another pull request for it?

[eddyb]

@newpav Sorry it didn't get linked. There's already a fix up, #37727.