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?

🤷

[SimonSapin]

“On its own” is important here.

#[unstable] is used for two categories of APIs:

• Those that are not stable yet, but have a tracking issue and might become stable at some point
• The "perma-unstable" APIs, that ideally should be private to a crate but need to be public typically to let some other standard library crate use them.

I think that depending on its category each item with #[unstable] should either point to a tracking issue, or be #[doc(hidden)]. Here “only for internal language use” seems to point to the latter.

[danielhenrymantilla]

Yeah, I share the feeling: AFAIC, feel free to go and make it #[doc(hidden)] again then

[raindev]

One potential argument against hiding the macro from the docs is that it shows up in the compiler errors originating from the use of format strings (i.e. "note: this error originates in the macro $crate::format_args_nl"). Having it surfaced to the user this way but hidden from the docs might not be great.

[jyn514]

This is being stabilized in #97658, so I think the answer is pretty clearly "no" now (but the discussion here is interesting for other perma-unstable macros).