RFC: re-export stdlib macros from submodules

[yoshuawuyts]

Summary

This RFC proposed we start re-exporting macros currently exposed in core::* from submodules. We define a mapping of which macros to re-export from which submodules, though in some cases it makes most sense to keep the macros exported from core.

This RFC does not yet propose we deprecate or migrate any code, that is left up to future RFCs.

---

Rendered

[joshtriplett]

Thanks for doing this work!

Nit: I don't think assert and family belong under core::panic, despite causing panics; I think they'd be more appropriate under a module assert or test or similar.

Also, even for some of the unstable macros, we may want to provide them in the prelude if we're not providing them in the crate root. assert_matches, for instance, like assert_eq, is most useful if it doesn't require importing.

[yoshuawuyts]

Nit: I don't think assert and family belong under core::panic, despite causing panics; I think they'd be more appropriate under a module assert or test or similar.

Yeah, that's fair. The first draft of this I shared on the libs Zulip had them under core::assert, but I changed it based on feedback. Both test and assert would be acceptable to me if that's what libs prefers.

Though I do have a preference for core::panic. I view panic! as a way to unconditionally trigger a panic, and assert! as a way to conditionally trigger a panic. Having them both co-located in the same module feels similar to me to anyhow's macros are structured, and I think would provide a useful overview of the various ways in which panics can be triggered.

[yoshuawuyts]

ping @rust-lang/libs-api: I don't believe there should be anything major preventing this from being accepted? Whether to export assert! as std::assert:assert! or std::panic::assert! feels like a relatively minor detail. Can I ask you to discuss this RFC during a future sync meeting? Thanks!

[m-ou-se]

This was discussed last week in the library API team meeting. We're generally on board with re-exporting macros in modules, but exactly which macro goes into which module still requires a lot of discussion.

So while we do think we should do this in general, we don't think we can accept this RFC as is, since we don't think the the proposed categorization/modularization of the macros is the right one. It might be better to have smaller separate proposals for individual categories/modules. (E.g. a proposal to move the formatting related macros to std::fmt, with its own motivation.)

We also briefly discussed what we would want to happen with new macros in the future. E.g. if we get a new formatting macro and all the existing ones are available in both std:: and std::fmt::, should the new one go in both or only in the latter, or both in the latter and reexported from the prelude, but not the crate root?

The RFC currently doesn't mention anything about the subtle differnce between macros that we export in the prelude (e.g. Clone) vs macros that live in the crate root (e.g. format) vs both (e.g. format_args). The current state of that seems to be more of an historical thing and not something that was done deliberately. But because #![no_implicit_prelude] is stable, it can be quite relevant. If we're going to have policies about where macros should live, we should probably also decide what that means for the prelude.

In the long term, we thought it might be good to 'hide' the original exports from the crate root. We'll keep them there for backwards compatibility (because someone can do std::println!() today), but it would be nice if we can clean it up from the reference documentation. A #[doc(hidden)] would probably too strong, but maybe some kind of #[doc(unlisted)] feature where it doesn't show up on the main page, but still exists in the search results, or something like that. (But that's something for later.)

[dhardy]

vs macros that live in the crate root (e.g. format)

This presumably refers to the use of #[macro_use] on injected extern crate std; which it has been proposed to remove: rust-lang/rust#53977

In the long term, we thought it might be good to 'hide' the original exports from the crate root. We'll keep them there for backwards compatibility (because someone can do std::println!() today),

Is it something that can and should be dealt with using editions?

This applies more to the prelude than macros explicitly used via std:: prefix. Is the cost of deprecation worse than the potential confusion of having an unexpected name in scope? (I didn't know module_path!() was a macro until just now, and posted this last week when I found Rust was not resolving the column! macro I thought it was.)