A collection of minor issues with the docs
- Version: 7
- Platform: NA
- Subsystem: NA
Hi, I've just finished reading the docs and made a few notes about some minor issues I found. I thought I'd dump them here, I can do a PR if appropriate. I might be misunderstanding some things so didn't want to jump in.
-
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 -
dgram.createSocket()
has two different signatures listed. One withtype
, one withobject
. https://nodejs.org/api/dgram.html#dgram_dgram_createsocket_type_callback That's cool, but the same sort of thing in thefs
module where anoptions
parameter could be a string defining the encoding, or an object that has an encoding property and something else is shown as a single signature. https://nodejs.org/api/fs.html#fs_fs_readfile_file_options_callback IMO they should both be likedgram
, that is,fs.readFile(file[, encoding], callback)
should be listed in addition tofs.readFile(file[, options], callback)
. But that means lots to change on the fs page. -
There is (very?) minor inconsistency in callback terminology. E.g. socket connect specifies a
connectListener
which is nice, it defines that this is a callback that is the same as 'listening' for theconnect
event. https://nodejs.org/api/net.html#net_socket_connect_options_connectlistener Butserver.listen
names the parameter justcallback
. https://nodejs.org/api/net.html#net_server_listen_options_callback Personally my choice would be the 'on' prefix followed by the event name that would trigger it.onConnect
,onListening
etc. I think that would make understanding when the callbacks are called easy. -
The example of a
dgam
sending message unnecessarily converts a string to a buffer, since it will be converted to a (utf8)Buffer
anyway. Less complexity in examples is better, right? (Also it vaguely implies that a string isn't as valid as a buffer.) https://nodejs.org/api/dgram.html#dgram_socket_send_msg_offset_length_port_address_callback -
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.codes
isn't documented. Is that on purpose? https://nodejs.org/api/zlib.html -
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 -
Getting picky here ... but 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