Why does the node documentation list this opening bracket before the comma when describing this function?

Question

Why does the node documentation list this opening bracket before the comma when describing this function?

fs.createReadStream(path[, options]) fs.createWriteStream(path[, options])

Translates into this: fs.readFile('/etc/passwd', 'utf-8', callback());

so why do they make it like this fs.createReadStream(path**[,** options]) and not like this fs.createReadStream(path, [options])

Am I missing something here?

Answer 1

When you see something like this in the doc:

fs.createReadStream(path[, options]) 

It means that the options argument is optional. It does not need to be passed. So you can fs.createReadStream() in either of these two ways:

fs.createReadStream(somePath)

or

fs.createReadStream(somePath, {flags: "r"});

The brackets [] are a documentation convention that the argument is optional and since the argument is optional, so is the comma that goes with it. That's why the commas is included inside the brackets. The comma is part of the optional part.

Answer 2

There is a difference between:

fs.createReadStream(path[, options])

and

fs.createReadStream(path, [options])

The first means that if you don't pass in the options then you don't put the comma. It means that the following are valid:

fs.createReadStream(path);
fs.createReadStream(path, 'utf-8');

The second means that if you don't pass in the options you cannot leave out the comma. It means that the following are valid:

fs.createReadStream(path,); // <---------------- NOTE THE COMMA
fs.createReadStream(path, 'utf-8');

Obviously this is wrong. Therefore the documentation correctly put the optional signifier [] around the comma.

This convention comes form a long tradition of unix man (manual) pages.

Answer 3

This is a convention for saying that the options argument is optional. Both call are valid:

 fs.createReadStream(onlyPath);
 fs.createReadStream(somePath, someOptions);