Should format_args_nl! be #[doc(hidden)] ?

[SimonSapin]

Initial title: format_args_nl! should link to format_args! where they mention it

---

https://doc.rust-lang.org/nightly/std/macro.format_args_nl.html currently contains:

Same as format_args, but adds a newline in the end.

It would be nicer as:

Same as format_args, but adds a newline in the end.

… although I also find #87410 which made it #[doc(hidden)]. It looks like that was undone at some point?

[name1e5s]

It seems that #[doc(hidden)] is removed in #92456

[name1e5s]

@rustbot claim

[SimonSapin]

It seems that #[doc(hidden)] is removed in #92456

Was it intentional, though? The PR description says

use ::std::prelude::v1::derive; compiles on stable, so, AFAIK, there is no reason to have it be #[doc(hidden)].

But that does not apply to format_args_nl which has:

    #[unstable(
        feature = "format_args_nl",
        issue = "none",
        reason = "`format_args_nl` is only for internal \
                  language use and is subject to change"
    )]

CC @danielhenrymantilla

[danielhenrymantilla]

After some discussion in that PR, it was deemed that a macro being unstable did not warrant, on its own, marking the macro as #[doc(hidden)]. Hence why a bunch of such macros were unhidden by that PR, but maybe format_args_nl! shouldn't have been part of those?

I really don't have a strong opinion here myself, so lemme wash my hands 😄, but:

• on the one hand, I do lean towards not hiding, in general, some of these unstable macros since it may reduce a bit too much their discoverability.

• on the other hand, I'll grant that there is a difference, alas quite subtle / currently hard-to-express, between unstable-and-expected-to-eventually-be-stabilized, and perma-unstable; for the latter it seems more legitimate to mark them as #[doc(hidden)].

  Given the description of the unstability of format_args_nl, it seems like it's the latter?

🤷