doc: Add useful V8 option section

[nimit95]

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[mscdex]

I think this should either be removed completely or at least reworded. Node does not restrict the V8 options that can be passed on the command line.

[nimit95]

There is another place in the document mentioning the same thing.

[jasnell]

Suggested change

	Sets the max memory size of V8 old memory section. As memory consumption approaches the limit, V8 will spend more time on garbage collection in an effort to free unused memory.
	On a machine with 2GB of memory it suggested to set 1.5GB to leave some memory for other uses and avoid swapping.
	Sets the max memory size of V8 old memory section. As memory
	consumption approaches the limit, V8 will spend more time on
	garbage collection in an effort to free unused memory.
	On a machine with 2GB of memory it suggested to set 1.5GB to
	leave some memory for other uses and avoid swapping.

nit: need to wrap lines at <= 80 chars

[sam-github]

Suggested change

These are v8 options and fall outside Node.js' responsibility.

V8 has CLI options. Any V8 CLI option that is provided to `node` will be passed on to V8 to handle. V8's options have _no stability guarantee_. The V8 team themselves don't consider them to be part of their formal API, and reserve the right to change them at any time. The Node.js team does not consider them covered by the Node.js stability guarantees. Many of the V8 options are of interest only to V8 developers. Despite this, there is a small set of V8 options that are widely applicable to Node.js, and they are documented here.

I think we should say something like the above.

[sam-github]

Suggested change

	### `--max-old-space-size`
	### `--max-old-space-size=SIZE` (in Mbytes)

[HarshithaKP]

according to me, explaning the gc behavior is not necessary while describing the heap size flag.

also, elaborate description about API stability can confuse people?

how about just this:
size of the javascript heap (tenured heap or old space), in MBs. (V8 options are not processed by Node.js, and are passed as is to V8)

[nimit95]

Detailed about V8 because people can get confused about the behaviour of GC, we are explicitly mentioning that it is managed by V8 here. Also, it doesn't lie in node preview.

[mscdex]

Suggested change

	set of V8 options that are widely applicable to the Node.js, and they are
	set of V8 options that are widely applicable to Node.js, and they are

[mscdex]

Suggested change

	documented here. V8 options that are allowed are:
	documented here:

[mscdex]

Suggested change

	On a machine with 2GB of memory it suggested to set 1.5GB
	On a machine with 2GB of memory it is suggested to set this to 1536 (1.5GB)

[mscdex]

Suggested change

	Sets the max memory size of V8 old memory section. As memory
	Sets the max memory size of V8's old memory section. As memory

[mscdex]

Just a note: when squashing/landing, make sure 'V8' is used instead of 'v8' in the commit message to avoid confusion.

[nimit95]

Anything to be done here from me?

[Trott]

Optional nit:

Suggested change

	and reserve the right to change them at any time. The Node.js team does not
	consider them covered by the Node.js stability guarantees. Many of the V8
	and reserve the right to change them at any time. Likewise, they are not
	covered by the Node.js stability guarantees. Many of the V8

[Trott]

Missing comma:

Suggested change

	On a machine with 2GB of memory it is suggested to set this to
	On a machine with 2GB of memory, it is suggested to set this to

Optional nit: I'm not a fan of "it is suggested" or "it is recommended" formulations. If possible, either tell people to do something or don't tell them at all. If you can't make a blanket statement, it might at least be a little more direct with something like "consider":

Suggested change

	On a machine with 2GB of memory it is suggested to set this to
	On a machine with 2GB of memory, consider setting this to

[nimit95]

Understood.

[Trott]

Optional nit: Delete this line.

[nimit95]

I personally feel an example helps a lot when being introduced to a flag. It clearly shows how to pass an argument. @Trott

[Trott]

I personally feel an example helps a lot when being introduced to a flag

If we want to provide an example, it should conform with the formatting of the other examples provided elsewhere in the doc. Otherwise, each entry is inventing its own example formatting, and we definitely do not want that. The existing format is more useful than this as it provides context, such as what the anticipated output might look like. So, this example might show the error one might get if running without the flag, then show the command succeeding with the flag.

(That said, most of our entries do not contain examples and that seems appropriate in this document.)

[nimit95]

Totally agree with your point, Can you point me to some of the correct existing formats?
What I see a mixture of formats, some given below

1. node --name-of-flag index.mjs
2. node --name-of-flag

[Trott]

I don't mean the format of the command itself. I mean the markdown formatting that denotes an example.

```console
$ node --cpu-prof index.js
$ ls *.cpuprofile
CPU.20190409.202950.15293.0.0.cpuprofile
```

[nimit95]

@Trott can you check out the formatting once now.

[addaleax]

@Trott do you want to apply your suggestions and merge this?

[nimit95]

Hey, will make the changes today. Totally forgot about this :)

[Trott]

My one remaining comment is a nit. In other words, it expresses my personal opinion, but I don't feel so strongly about it that I would block landing this if others disagree with my view. So if @addaleax or anyone else thinks this should land now as it is, go for it.

[gireeshpunathil]

landed in df05b07