doc: add initial constants module documentation

[jasnell]

Checklist

• documentation is changed or added

Affected core subsystem(s)

doc (constants)

Description of change

This is a work in progress

Begin documentation of the constants module.
/cc @nodejs/documentation @addaleax @nodejs/crypto

Note to @nodejs/crypto: there appear to be several of the openssl related constants that are not recommended for use. I'd recommend that we indicate those and possible even do a hard deprecation for those at some point (but not in this PR)

Refs: #6492, #6494

[addaleax]

Markdown typo here :)

[jasnell]

Sigh ... fat fingers

[addaleax]

I’d add something like:

This flag is meant for use with [`fs.access()`][].

to (each of?) these, otherwise people might confuse them with O_RDONLY etc.

[`fs.access()`]: fs.html#fs_fs_access_path_mode_callback

[addaleax]

Cool, definitely thanks for the work you put into this!

[jasnell]

Of course. It's not very helpful for me to complain about there not being documentation for something unless I'm willing to help get the documentation put together, right? ;-)

[Fishrock123]

this is big enough I think it warrants direct ctc coversation

[jasnell]

@nodejs/ctc ... Any thoughts on this?
@Fishrock123 ... Any specific concerns?

[eljefedelrodeodeljefe]

Would a table not suite the plenty constants better?

[jasnell]

Possibly. Went with this initially because it's a closer fit to the
existing doc style. Personally I'd prefer something more compact tho
(actually, what I'd really prefer is for these to be documented with and
exposed by the modules for which they are most relevant)
On May 1, 2016 5:08 PM, "Robert Jefe Lindstädt" [email protected]
wrote:

Would a table not suite the plenty constants better?

—
You are receiving this because you authored the thread.
Reply to this email directly or view it on GitHub
#6505 (comment)

[eljefedelrodeodeljefe]

Ah, you mean like the "events"-section. That sounds even better. Would be hugely favoring this.

[Fishrock123]

Link to the Errors documentation page maybe?

[jasnell]

Can, but those are far from complete. We should either fill those out there more or move that detail into here. How those are documented leaves much to be desired.

[Fishrock123]

Is the object returned by constants actually read-only? Should we be freezing this or something?

[addaleax]

@Fishrock123 No, only the constants themselves are all read-only properties, at least right now.

[cjihrig]

Missing period at the end of the line.

[jasnell]

@cjihrig ... Thanks for the edits, I have yet to go through and do a proofread through this. Before I got too far into it tho, we need to decide if we even want to document these in this way or take a different approach. I wouldn't want you to spend too much time doing a proofread if we ultimately decide not to do this.

[jasnell]

Closing in favor of #6534