doc: add documentation for deprecation properties

[maclover7]

Refs: #16394

Relevant commit history:

• node: Add --throw-deprecation
• Add --no-deprecation and --trace-deprecation flags

cc @vsemozhetbyt, I tried to avoid duplicating tons of documentation by linking out to other sections of the process docs, would love your thoughts :)

Checklist

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

Affected core subsystem(s)

doc

[refack]

Code LGTM, but the question is should they be documented or removed. AFAICT they were exposed as a rough mechanism of communicating the CLI flags to JS, they are not necessarily part of a succinct API.

Alternatively they (and other CLI flag mappings) could go behind a new process.cliArgs() API endpoint.

[vsemozhetbyt]

A nit: --trace-deprecation -> --throw-deprecation

[vsemozhetbyt]

It seems this should be placed after the process.title, ABC-wise.

[maclover7]

my bad -- don't know why I thought a ### about IO was a ## 😞

[vsemozhetbyt]

I am not sure about some things.

1. Can we say that the type is boolean if the value is undefined in case of the CLI key is not set?

console.log(
  process.noDeprecation, process.throwDeprecation, process.traceDeprecation
);

undefined undefined undefined

2. Should we note that these properties are not just a mirrors of the CLI keys, but they can affect the warning behavior as per util.md notes.

3. Should we duplicate the precedence note?

Let's see what other collaborators think.

[vsemozhetbyt]

@refack It seems we cannot just remove them as they have been documented in util doc some years. We can deprecate them, but we may still need to document them for that in the proper place.

[vsemozhetbyt]

BTW, thank you for the PR and digging into the history!

[addaleax]

Alternatively they (and other CLI flag mappings) could go behind a new process.cliArgs() API endpoint.

Like process.execArgv? ;)

[refack]

Alternatively they (and other CLI flag mappings) could go behind a new process.cliArgs() API endpoint.
Like process.execArgv? ;)

Hence my ambivalence about fully embracing those flags as 1st class API citizens 😕
Although process.execArgv still requires parsing and does not take into account NODE_OPTIONS

[BridgeAR]

I personally think it would be best to deprecate these instead of documenting them. At the same time we can rephrase the util part where they are mentioned.

[maclover7]

@BridgeAR Even if the props are deprecated publicly, they are still used within parts of Node core (like lib/internal/process/warning.js for example), so I'm not sold on what the maintenance benefit would be for doing that :(

[BridgeAR]

@maclover7 even if we use some internally it does not mean users should always use those things as well. That is what internal is all about. At least that is how I see it. So it is not about a maintenance benefit but about being able to change internal details and or not overloading the user with information that does not improve anything.

[nylen]

Please document and standardize these properties. I want to use process.throwDeprecation = true; in my code so that I don't have to start node with --throw-deprecation.

Edit: See also #17871

[cjihrig]

Possibly change "returns if" to "indicates whether or not"

[apapirovski]

I would go with just "indicates whether", without the "or not".

[cjihrig]

Same comment here and below.

[maclover7]

updated @cjihrig @apapirovski

[maclover7]

ping @cjihrig @apapirovski would like to try and land this

[cjihrig]

The changes themselves look fine, but there were a few comments by others that brought up the alternative of deprecating and removing these properties.

[maclover7]

CI: https://ci.nodejs.org/job/node-test-commit-light/88/

[maclover7]

Going to open a followup issue to discuss possible deprecation/removal of the properties.

[maclover7]

c770f43