doc: clarify util.inspect usage intent

[devsnek]

commit from #16956 moved to separate pr by request of @addaleax

Checklist

• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

[Trott]

No bold text please.

[Trott]

Is the added text true? Might we not consider a significant change to util.inspect() a breaking change? /cc @nodejs/tsc

[Trott]

(Change looks good to me if it's accurate, of course. Would definitely prefer no bold text. We overuse arbitrary typographical emphasis in our docs.)

[evanlucas]

I know I mentioned that we should document it in the other issue if that is the case, but I'm pretty against this. I have code that relies on the output of util.inspect and I know that others in the ecosystem do as well.

[devsnek]

i feel like relying on the output of something that's designed to present human readable information is kinda irresponsible, perhaps we can land this in 10, and then @@toStringTag in 11?

[addaleax]

I personally think this warning is a good idea.

In particular, this does not mean that we can’t consider breaking changes to util.inspect semver-major in the future, just that relying on its output is a bad practice.

[thefourtheye]

Would it be better if we called this out in a separate note or warning section, so that the importance of this is highlighted?

[Trott]

Would it be better if we called this out in a separate note or warning section, so that the importance of this is highlighted?

TL;DR: No. :-D

I'd rather not give it undue weight. We've survived this long without a note at all. We can always emphasize it if it becomes apparent that it's critical (which, honestly, won't happen). We have a tendency to want all new notes to be set off in a separate bolded or italicized or otherwise-highlighted note. By emphasizing everything, we emphasize nothing. Honestly, this information is good to have, but not more important than lots of other things in the doc.

[mcollina]

LGTM

[addaleax]

@devsnek Could you rebase this?

[devsnek]

@addaleax done 👍

[addaleax]

I would like to land this in the next few days unless there are objections.

[BridgeAR]

Somehow this sounds a bit harsh to me. Would you be fine to change it to something like

The `util.inspect()` method returns a string representation of `object` that is
primarily intended for debugging. Additional `options` may be passed that alter
certain aspects of the formatted string.
Note that the output of `util.inspect` may undergo minor changes from time to
time without a semver-major step. Programmatically relying on the output is
therefore not recommended.

[devsnek]

i kinda want it to be harsh, there's a reason stuff like internalBinding has to be a thing now

[BridgeAR]

With your comment in place as is I would argue that landing #17576 as new default without putting it behind a option could be done as a semver-patch. And I do not see that at all.

[gibfahn]

With your comment in place as is I would argue that landing #17576 as new default without putting it behind a option could be done as a semver-patch. And I do not see that at all.

I'd rather we be harsher in the docs , but more conservative when actually landing possibly breaking PRs, so +1 on keeping this wording, but making #17576 major.

Realistically we know that if enough people depend on the output of util.inspect, no matter how internal, we won't be able to change it. But if this warning helps dissuade people from relying on that output, then that seems like a good thing.

Also if this PR makes #17576 a patch, that would make this PR semver-major 😁 .

[BridgeAR]

Landed in 3b98038