Doc fixes
Checklist
-
documentation is changed or added -
commit message follows commit guidelines
Affected core subsystem(s)
doc
Description of change
This fixes a number of issues in the documentation, originally logged as an issue here. As suggested by @bnoordhuis I have combined them in a single PR with 14 commits.
The relevant items (copied from the original issue I logged):
-
Should
tls.connect()
listhost
andport
in the options if they're already params? https://nodejs.org/api/tls.html#tls_tls_connect_port_host_options_callback -
Seems weird that
path.resolve()
arguments are optional. Worth documenting that the method returns'.'
if you pass nothing in? https://nodejs.org/api/path.html#path_path_join_paths https://nodejs.org/api/path.html#path_path_resolve_paths -
The params for
path.format()
andpath.parse()
are in different orders,format()
is logically wrong based on the diagram underparse()
https://nodejs.org/api/path.html#path_path_format_pathobject https://nodejs.org/api/path.html#path_path_parse_path -
There shouldn't be spaces in
tlsSocket.getPeerCertificate([ detailed ])
https://nodejs.org/api/tls.html#tls_tlssocket_getpeercertificate_detailed -
net.Server
showsconnections
as deprecated... https://nodejs.org/api/net.html#net_server_connectionstls.Server
inherits from this, but doesn't showconnections
as deprecated https://nodejs.org/api/tls.html#tls_server_connections Should it? -
Is the
encoding
parameter allowed if thedata
parameter isn't set? Should: request.end([data][, encoding][, callback]) be: request.end([data[, encoding]][, callback]) ? https://nodejs.org/api/http.html#http_request_end_data_encoding_callback -
dgram
has a header "dgram module functions" before the static methods, none of the other pages do this. Is the dgram module different, or is this just an inconsistency? https://nodejs.org/api/dgram.html#dgram_dgram_module_functions -
Parameter names are almost always camelCase, except in crypto where they're snake_case. https://nodejs.org/api/crypto.html#crypto_cipher_final_output_encoding Is that an inconsistency or is there meaning in that?
-
Using
util.inspect()
insideconsole.log()
is redundant (I think. Isn't it?) https://nodejs.org/api/events.html#events_emitter_listeners_eventname https://nodejs.org/api/vm.html#vm_vm_runincontext_code_contextifiedsandbox_options https://nodejs.org/api/vm.html#vm_script_runinnewcontext_sandbox_options -
Missing apostrophe in "run using the vm modules methods" https://nodejs.org/api/vm.html#vm_what_does_it_mean_to_contextify_an_object
-
I have no idea about this one, but is sandbox really optional in
script.runInNewContext()
? If I callscript.runInNewContext(options)
, wouldn't it try and make a sandbox out of the options object? I went looking through the source but found myself in a strange land and gave up. https://nodejs.org/api/vm.html#vm_script_runinnewcontext_sandbox_options -
zlib.constants
is missing "added in version..." (and is quite new so this is a problem) https://nodejs.org/api/zlib.html#zlib_zlib_constants Looks like this commit https://github.com/nodejs/node/commit/197a4652807bf1d830d67c1d8a4aecdf35fda6a4#diff-c245d87dba893de0b77c7574f0081633R388 -
zlib
methods all haveoptions
as an argument, but not shown in square brackets (but in the TOC they're shown in square brackets). Less important, but having the word in the argument list be linked is inconsistent with the other pages. The description contains the word 'options' which is linked to the class options section. -
Wording is strange for zlib methods, e.g. "Returns a new
Deflate
object with an options." By comparison, innet.connect()
the equivalent wording is something like "The options are passed to thenet.Socket
constructor" https://nodejs.org/api/zlib.html -
The wording for there being Sync version of methods is different for
fs
andzlib
. https://nodejs.org/api/zlib.html#zlib_convenience_methods https://nodejs.org/api/fs.html#fs_file_system