add internal documentation

[aymen94]

Added internal documentation for contributors.

#26639

If it's accepted, I'll add more.

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

[aymen94]

@Trott

[Trott]

Seems OK to me, but here are the relevant questions for @nodejs/collaborators

• This documents an internal-use flag but does it outside of the API documentation (so it won't appear on the nodejs.org website, for example). It's still a public document though, available on GitHub and in the source code. Do we want to document internal-use flags? Or is it actually best to just not have them documented anywhere at all because doing so will invariably encourage people to use them, which is exactly what we don't want? @bnoordhuis

• We already have internal docs in doc/guides. I dislike that directory name and maybe we can change it some time. But for now, does it make sense to split this into another directory like it is here (doc/internal) perhaps with the hope of moving everything there eventually? Or should we keep it with everything else in doc/guides?

• While it seems more-or-less OK to me (as in: better than not having it documented at all), I feel like the documentation for this flag is not quite correct, or at least could stand some significant improvements that wouldn't be that big of a problem to add. It should mention bootstrap code, no? @danbev @joyeecheung

[mscdex]

If it's internal-only it's typically only used in tests right? If so, it might be better to place it in the tests documentation?

[joyeecheung]

Thanks for adding more docs for internals!

@Trott I think for now, doc/guides is the best place for this.

[joyeecheung]

Can you move this into doc/guides? I guess then a name like internal-flags.md (if we focus this document on flags) or developing-core.md/debugging-internals.md would be more suitable.

[danbev]

@Trott Like @joyeecheung said I think the place for this is in doc/guides which was suggested in the original pr.

[aymen94]

@danbev There are other undocumented things besides this --inspect-brk-node.
Is my opinion: I think we should add an internal doc, Also to remember that there are in the code.
@Trott @joyeecheung

[joyeecheung]

@aymen94 There already are several internal docs under doc/guides, this just adds some more for the CLI flags, so it should be there as well.

[sam-github]

Why not just actually document our CLI options? I can never remember the name of --expose-internal and every time I grep the test source to find its name I ask myself "why?". If we don't want to be pinned down on the feature, call it experimental.

If this CLI option, which I've never heard about (probably because its not documented!) does what it sounds like, I wish I'd know about it before.

Wrt. the text proposed here, I think the option allows debugging the javascript js built into node during its initial evaluation, right? That isn't clear enough, I think, because I'm not absolutely certain that's what its for.

[ryzokuken]

Don't want to be the naysayer here, but the downsides of having extensive internal documentation in my opinion:

1. It adds to the time and effort required for making code changes. It is one thing to document the changes to the public API, and a completely different thing altogether to ask people to document the internals. Most contributors would either end up overextending themselves or not reaching some vague undocumented standards.
2. As rightly pointed out by @Trott, this would inevitably lead to the ecosystem getting a know a lot about the internals (read: implementation details) of Node.js. Since we've set a terrible precedent regarding breaking code that relies on implementation details or experimental features (I've have to deal with it myself while working on module: use compileFunction over Module.wrap #21573, for example), I'm afraid this might end up revealing too much and it might significantly affect our ability to improve the codebase unless we explicitly agree that it's fine to change anything that's not a part of our public API, even if it might break someone's code.

[aymen94]

@ryzokuken If not traced, many contributors will forget or do not know that there are.

[richardlau]

Maybe we should rename --inspect-brk-node? It's not obvious at all that it's not intended for general use.

[ryzokuken]

@ryzokuken If not traced, many contributors will forget or do not know that there are.

Contributors will forget that certain options exist? I think that seems unlikely.

[aymen94]

@ryzokuken It's for new contributors like me?
Only looking at the source code, I see that they are there.

[danbev]

I can never remember the name of --expose-internal and every time I grep the test source to find its name

I'm the same but have started using bash completion (--completion-bash flag) which I think helps. You might not be using bash but though I'd mention it just in case.

[thefourtheye]

Double script sounds redundant to me. Perhaps, JavaScript code?

[joyeecheung]

statement is probably more accurate (it won't break on the first declaration).

[antsmartian]

I agree with most of the points mentioned out by @Trott . Wanted to give a few more ideas like if we agree on creating these documentation, then we can open up a issue (should be a help-wanted and good-first-issue) so that we can get contribution(like this one), which will eventually grow and cover all these internal used stuffs. Then, we can add those documentation in new contributions list or somewhere, so that new people coming to read our source code can get benefited by. I guess its a win-win situation.

[sam-github]

@danbev I use zsh, but bash things often work, I'll give it a try, thanks.

[joyeecheung]

As rightly pointed out by @Trott, this would inevitably lead to the ecosystem getting a know a lot about the internals (read: implementation details) of Node.js.

I don't think adding internal documentations really makes a difference here. For people who want to hack internals, they'll be able to find out about these things either by reading code or by reading blog posts etc. (TBH our doc folder may be the last place they'll ever look at). If we really want to hide all the internals, we might as well never write explanatory comments in the code, but that hardly benefits anyone. We just need to be very clear that these are not features, but helpers for debugging and are likely to go away without any prior notice.

Either way, It'll probably take some time before documentation like this show up in significant places of the search results, if it ever gets there - if you don't know about the keywords, it's probably hard to find out about the document, but if you already do, then you may already have a better source of knowledge than this document.

[Trott]

Lots of people have commented, and there's been debate about details like whether this documentation should go in one directory or another, but no Collaborator has come on with a strong +1 or -1 just for the general concept of documenting our internal-use-only flags someplace for ourselves. Where do individual Collaborators stand on that?

[Trott]

(I would interpret joyeecheung as being +1, ryzokuken as being -1, danbev as +1, etc., but those are inferences on my part and I could very well be wrong. I'm asking people to be explicit.)

[danbev]

I don't feel strongly about this, I'm fine either with documenting this and fine if we don't.

[joyeecheung]

I am +1, but I think it should be in doc/guides, or it should be together with other documents under doc/guides (the folder can be renamed, not necessarily in this PR)

[targos]

I'm +1 as well. If we are afraid that people might mistake it for general documentation, we can add a clear disclaimer at the top of the document.

[BridgeAR]

When reading the comments it sounds like the common opinion is to add the documentation, but only to doc/guides. @aymen94 would you mind moving the file accordingly and to add a disclaimer as suggested?