From f2a78de6ec134f4050531ba6a52dee47e0aee165 Mon Sep 17 00:00:00 2001
From: Trevor Norris <trev.norris@gmail.com>
Date: Mon, 29 Sep 2014 16:32:34 -0700
Subject: [PATCH] doc: fix optional parameter parsing

The parameter parser specifically looked for the old bracket syntax.
This generated a lot of warnings when building the docs. Those warnings
have been fixed by changing the parsing logic.

Signed-off-by: Trevor Norris <trev.norris@gmail.com>
---
 doc/api/assert.markdown        |  2 +-
 doc/api/buffer.markdown        | 10 +++++-----
 doc/api/child_process.markdown | 10 +++++-----
 doc/api/console.markdown       | 10 +++++-----
 doc/api/crypto.markdown        | 10 +++++-----
 doc/api/dgram.markdown         | 32 +++++++++++++++++++++++---------
 doc/api/events.markdown        |  2 +-
 doc/api/fs.markdown            |  2 +-
 doc/api/http.markdown          | 12 ++++++------
 doc/api/https.markdown         |  2 +-
 doc/api/net.markdown           | 16 ++++++++--------
 doc/api/path.markdown          |  2 +-
 doc/api/querystring.markdown   |  4 ++--
 doc/api/smalloc.markdown       | 34 ++++++++++++++++++----------------
 doc/api/stream.markdown        |  4 ++--
 doc/api/timers.markdown        |  6 +++---
 doc/api/tls.markdown           |  6 +++---
 doc/api/url.markdown           |  2 +-
 doc/api/vm.markdown            |  4 ++--
 tools/doc/json.js              | 11 ++++++-----
 20 files changed, 99 insertions(+), 82 deletions(-)

diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown
index dec971e..0fb7f0b 100644
--- a/doc/api/assert.markdown
+++ b/doc/api/assert.markdown
@@ -37,7 +37,7 @@ Tests strict equality, as determined by the strict equality operator ( `===` )
 
 Tests strict non-equality, as determined by the strict not equal operator ( `!==` )
 
-## assert.throws(block[, error]\[, message])
+## assert.throws(block[, error][, message])
 
 Expects `block` to throw an error. `error` can be constructor, `RegExp` or
 validation function.
diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown
index 4920533..fb86acc 100644
--- a/doc/api/buffer.markdown
+++ b/doc/api/buffer.markdown
@@ -162,7 +162,7 @@ buffer object.  It does not change when the contents of the buffer are changed.
     // 1234
     // 1234
 
-### buf.write(string[, offset]\[, length]\[, encoding])
+### buf.write(string[, offset][, length][, encoding])
 
 * `string` String - data to be written to buffer
 * `offset` Number, Optional, Default: 0
@@ -181,7 +181,7 @@ The method will not write partial characters.
     console.log(len + " bytes: " + buf.toString('utf8', 0, len));
 
 
-### buf.toString([encoding]\[, start]\[, end])
+### buf.toString([encoding][, start][, end])
 
 * `encoding` String, Optional, Default: 'utf8'
 * `start` Number, Optional, Default: 0
@@ -252,7 +252,7 @@ Returns a number indicating whether `this` comes before or after or is
 the same as the `otherBuffer` in sort order.
 
 
-### buf.copy(targetBuffer[, targetStart]\[, sourceStart]\[, sourceEnd])
+### buf.copy(targetBuffer[, targetStart][, sourceStart][, sourceEnd])
 
 * `targetBuffer` Buffer object - Buffer to copy into
 * `targetStart` Number, Optional, Default: 0
@@ -283,7 +283,7 @@ into `buf2`, starting at the 8th byte in `buf2`.
     // !!!!!!!!qrst!!!!!!!!!!!!!
 
 
-### buf.slice([start]\[, end])
+### buf.slice([start][, end])
 
 * `start` Number, Optional, Default: 0
 * `end` Number, Optional, Default: `buffer.length`
@@ -703,7 +703,7 @@ Example:
     // <Buffer 43 eb d5 b7 dd f9 5f d7>
     // <Buffer d7 5f f9 dd b7 d5 eb 43>
 
-### buf.fill(value[, offset]\[, end])
+### buf.fill(value[, offset][, end])
 
 * `value`
 * `offset` Number, Optional
diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown
index 4cfad55..7db4882 100644
--- a/doc/api/child_process.markdown
+++ b/doc/api/child_process.markdown
@@ -303,7 +303,7 @@ child process has any open IPC channels with the parent (i.e `fork()`).
 These methods follow the common async programming patterns (accepting a
 callback or returning an EventEmitter).
 
-### child_process.spawn(command[, args]\[, options])
+### child_process.spawn(command[, args][, options])
 
 * `command` {String} The command to run
 * `args` {Array} List of string arguments
@@ -531,7 +531,7 @@ amount of data allowed on stdout or stderr - if this value is exceeded then
 the child process is killed.
 
 
-### child_process.execFile(file[, args]\[, options]\[, callback])
+### child_process.execFile(file[, args][, options][, callback])
 
 * `file` {String} The filename of the program to run
 * `args` {Array} List of string arguments
@@ -555,7 +555,7 @@ subshell but rather the specified file directly. This makes it slightly
 leaner than `child_process.exec`. It has the same options.
 
 
-### child_process.fork(modulePath[, args]\[, options])
+### child_process.fork(modulePath[, args][, options])
 
 * `modulePath` {String} The module to run in the child
 * `args` {Array} List of string arguments
@@ -598,7 +598,7 @@ Blocking calls like these are mostly useful for simplifying general purpose
 scripting tasks and for simplifying the loading/processing of application
 configuration at startup.
 
-### child_process.spawnSync(command[, args]\[, options])
+### child_process.spawnSync(command[, args][, options])
 
 * `command` {String} The command to run
 * `args` {Array} List of string arguments
@@ -629,7 +629,7 @@ until the process has completely exited. That is to say, if the process handles
 the `SIGTERM` signal and doesn't exit, your process will wait until the child
 process has exited.
 
-### child_process.execFileSync(command[, args]\[, options])
+### child_process.execFileSync(command[, args][, options])
 
 * `command` {String} The command to run
 * `args` {Array} List of string arguments
diff --git a/doc/api/console.markdown b/doc/api/console.markdown
index 82860c1..46ab65f 100644
--- a/doc/api/console.markdown
+++ b/doc/api/console.markdown
@@ -22,7 +22,7 @@ In daily use, the blocking/non-blocking dichotomy is not something you
 should worry about unless you log huge amounts of data.
 
 
-## console.log([data]\[, ...])
+## console.log([data][, ...])
 
 Prints to stdout with newline. This function can take multiple arguments in a
 `printf()`-like way. Example:
@@ -34,15 +34,15 @@ Prints to stdout with newline. This function can take multiple arguments in a
 If formatting elements are not found in the first string then `util.inspect`
 is used on each argument.  See [util.format()][] for more information.
 
-## console.info([data]\[, ...])
+## console.info([data][, ...])
 
 Same as `console.log`.
 
-## console.error([data]\[, ...])
+## console.error([data][, ...])
 
 Same as `console.log` but prints to stderr.
 
-## console.warn([data]\[, ...])
+## console.warn([data][, ...])
 
 Same as `console.error`.
 
@@ -82,7 +82,7 @@ Finish timer, record output. Example:
 Print to stderr `'Trace :'`, followed by the formatted message and stack trace
 to the current position.
 
-## console.assert(value[, message]\[, ...])
+## console.assert(value[, message][, ...])
 
 Similar to [assert.ok()][], but the error message is formatted as
 `util.format(message...)`.
diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown
index 0359d9a..4e465d6 100644
--- a/doc/api/crypto.markdown
+++ b/doc/api/crypto.markdown
@@ -214,7 +214,7 @@ writable.  The written plain text data is used to produce the
 encrypted data on the readable side.  The legacy `update` and `final`
 methods are also supported.
 
-### cipher.update(data[, input_encoding]\[, output_encoding])
+### cipher.update(data[, input_encoding][, output_encoding])
 
 Updates the cipher with `data`, the encoding of which is given in
 `input_encoding` and can be `'utf8'`, `'ascii'` or `'binary'`.  If no
@@ -280,7 +280,7 @@ writable.  The written enciphered data is used to produce the
 plain-text data on the the readable side.  The legacy `update` and
 `final` methods are also supported.
 
-### decipher.update(data[, input_encoding]\[, output_encoding])
+### decipher.update(data[, input_encoding][, output_encoding])
 
 Updates the decipher with `data`, which is encoded in `'binary'`,
 `'base64'` or `'hex'`.  If no encoding is provided, then a buffer is
@@ -408,7 +408,7 @@ Creates a Diffie-Hellman key exchange object and generates a prime of
 `prime_length` bits and using an optional specific numeric `generator`.
 If no `generator` is specified, then `2` is used.
 
-## crypto.createDiffieHellman(prime[, prime_encoding]\[, generator]\[, generator_encoding])
+## crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding])
 
 Creates a Diffie-Hellman key exchange object using the supplied `prime` and an
 optional specific `generator`.
@@ -442,7 +442,7 @@ the public key in the specified encoding. This key should be
 transferred to the other party. Encoding can be `'binary'`, `'hex'`,
 or `'base64'`.  If no encoding is provided, then a buffer is returned.
 
-### diffieHellman.computeSecret(other_public_key[, input_encoding]\[, output_encoding])
+### diffieHellman.computeSecret(other_public_key[, input_encoding][, output_encoding])
 
 Computes the shared secret using `other_public_key` as the other
 party's public key and returns the computed shared secret. Supplied
@@ -541,7 +541,7 @@ Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or
 Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided,
 then a buffer is returned.
 
-### ECDH.computeSecret(other_public_key[, input_encoding]\[, output_encoding])
+### ECDH.computeSecret(other_public_key[, input_encoding][, output_encoding])
 
 Computes the shared secret using `other_public_key` as the other
 party's public key and returns the computed shared secret. Supplied
diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown
index 33541e4..09bacaf 100644
--- a/doc/api/dgram.markdown
+++ b/doc/api/dgram.markdown
@@ -22,13 +22,8 @@ You have to change it to this:
 
 
 ## dgram.createSocket(type[, callback])
-## dgram.createSocket(options[, callback])
 
 * `type` String. Either 'udp4' or 'udp6'
-* `options` Object. Should contain a `type` property and could contain
-  `reuseAddr` property. `false` by default.
-  When `reuseAddr` is `true` - `socket.bind()` will reuse address, even if the
-  other process has already bound a socket on it.
 * `callback` Function. Attached as a listener to `message` events.
   Optional
 * Returns: Socket object
@@ -38,9 +33,28 @@ and `udp6`.
 
 Takes an optional callback which is added as a listener for `message` events.
 
-Call `socket.bind` if you want to receive datagrams. `socket.bind()` will bind
-to the "all interfaces" address on a random port (it does the right thing for
-both `udp4` and `udp6` sockets). You can then retrieve the address and port
+Call `socket.bind()` if you want to receive datagrams. `socket.bind()` will
+bind to the "all interfaces" address on a random port (it does the right thing
+for both `udp4` and `udp6` sockets). You can then retrieve the address and port
+with `socket.address().address` and `socket.address().port`.
+
+## dgram.createSocket(options[, callback])
+* `options` Object
+* `callback` Function. Attached as a listener to `message` events.
+* Returns: Socket object
+
+The `options` object should contain a `type` field of either `udp4` or `udp6`
+and an optional boolean `reuseAddr` field.
+
+When `reuseAddr` is true `socket.bind()` will reuse the address, even if
+another process has already bound a socket on it. `reuseAddr` defaults to
+`false`.
+
+Takes an optional callback which is added as a listener for `message` events.
+
+Call `socket.bind()` if you want to receive datagrams. `socket.bind()` will
+bind to the "all interfaces" address on a random port (it does the right thing
+for both `udp4` and `udp6` sockets). You can then retrieve the address and port
 with `socket.address().address` and `socket.address().port`.
 
 ## Class: dgram.Socket
@@ -142,7 +156,7 @@ a packet might travel, and that generally sending a datagram greater than
 the (receiver) `MTU` won't work (the packet gets silently dropped, without
 informing the source that the data did not reach its intended recipient).
 
-### socket.bind(port[, address]\[, callback])
+### socket.bind(port[, address][, callback])
 
 * `port` Integer
 * `address` String, Optional
diff --git a/doc/api/events.markdown b/doc/api/events.markdown
index 82e736d..895debb 100644
--- a/doc/api/events.markdown
+++ b/doc/api/events.markdown
@@ -104,7 +104,7 @@ Returns an array of listeners for the specified event.
     console.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
 
 
-### emitter.emit(event[, arg1]\[, arg2]\[, ...])
+### emitter.emit(event[, arg1][, arg2][, ...])
 
 Execute each of the listeners in order with the supplied arguments.
 
diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown
index af3a342..c6bfa24 100644
--- a/doc/api/fs.markdown
+++ b/doc/api/fs.markdown
@@ -568,7 +568,7 @@ have effectively stopped watching `filename`.
 Calling `fs.unwatchFile()` with a filename that is not being watched is a
 no-op, not an error.
 
-## fs.watch(filename[, options]\[, listener])
+## fs.watch(filename[, options][, listener])
 
     Stability: 2 - Unstable.
 
diff --git a/doc/api/http.markdown b/doc/api/http.markdown
index e94f631..827bba6 100644
--- a/doc/api/http.markdown
+++ b/doc/api/http.markdown
@@ -64,7 +64,7 @@ Returns a new web server object.
 The `requestListener` is a function which is automatically
 added to the `'request'` event.
 
-## http.createClient([port]\[, host])
+## http.createClient([port][, host])
 
 This function is **deprecated**; please use [http.request()][] instead.
 Constructs a new HTTP client. `port` and `host` refer to the server to be
@@ -160,7 +160,7 @@ If a client connection emits an 'error' event - it will forwarded here.
 `socket` is the `net.Socket` object that the error originated from.
 
 
-### server.listen(port[, hostname]\[, backlog]\[, callback])
+### server.listen(port[, hostname][, backlog][, callback])
 
 Begin accepting connections on the specified port and hostname.  If the
 hostname is omitted, the server will accept connections directed to any
@@ -275,7 +275,7 @@ After this event, no more events will be emitted on the response object.
 Sends a HTTP/1.1 100 Continue message to the client, indicating that
 the request body should be sent. See the ['checkContinue'][] event on `Server`.
 
-### response.writeHead(statusCode[, statusMessage]\[, headers])
+### response.writeHead(statusCode[, statusMessage][, headers])
 
 Sends a response header to the request. The status code is a 3-digit HTTP
 status code, like `404`. The last argument, `headers`, are the response headers.
@@ -433,7 +433,7 @@ emit trailers, with a list of the header fields in its value. E.g.,
     response.end();
 
 
-### response.end([data]\[, encoding])
+### response.end([data][, encoding])
 
 This method signals to the server that all of the response headers and body
 have been sent; that server should consider this message complete.
@@ -878,7 +878,7 @@ The `encoding` argument is optional and only applies when `chunk` is a string.
 Defaults to `'utf8'`.
 
 
-### request.end([data]\[, encoding])
+### request.end([data][, encoding])
 
 Finishes sending the request. If any parts of the body are
 unsent, it will flush them to the stream. If the request is
@@ -901,7 +901,7 @@ Once a socket is assigned to this request and is connected
 Once a socket is assigned to this request and is connected
 [socket.setNoDelay()][] will be called.
 
-### request.setSocketKeepAlive([enable]\[, initialDelay])
+### request.setSocketKeepAlive([enable][, initialDelay])
 
 Once a socket is assigned to this request and is connected
 [socket.setKeepAlive()][] will be called.
diff --git a/doc/api/https.markdown b/doc/api/https.markdown
index e95097c..464677e 100644
--- a/doc/api/https.markdown
+++ b/doc/api/https.markdown
@@ -55,7 +55,7 @@ Or
     }).listen(8000);
 
 
-### server.listen(port[, host]\[, backlog]\[, callback])
+### server.listen(port[, host][, backlog][, callback])
 ### server.listen(path[, callback])
 ### server.listen(handle[, callback])
 
diff --git a/doc/api/net.markdown b/doc/api/net.markdown
index 36864f2..2881d44 100644
--- a/doc/api/net.markdown
+++ b/doc/api/net.markdown
@@ -6,7 +6,7 @@ The `net` module provides you with an asynchronous network wrapper. It contains
 methods for creating both servers and clients (called streams). You can include
 this module with `require('net');`
 
-## net.createServer([options]\[, connectionListener])
+## net.createServer([options][, connectionListener])
 
 Creates a new TCP server. The `connectionListener` argument is
 automatically set as a listener for the ['connection'][] event.
@@ -107,8 +107,8 @@ changed to
 
     var client = net.connect({path: '/tmp/echo.sock'});
 
-## net.connect(port[, host]\[, connectListener])
-## net.createConnection(port[, host]\[, connectListener])
+## net.connect(port[, host][, connectListener])
+## net.createConnection(port[, host][, connectListener])
 
 Creates a TCP connection to `port` on `host`. If `host` is omitted,
 `'localhost'` will be assumed.
@@ -130,7 +130,7 @@ A factory method which returns a new ['net.Socket'](#net_class_net_socket).
 
 This class is used to create a TCP or local server.
 
-### server.listen(port[, host]\[, backlog]\[, callback])
+### server.listen(port[, host][, backlog][, callback])
 
 Begin accepting connections on the specified `port` and `host`.  If the
 `host` is omitted, the server will accept connections directed to any
@@ -352,7 +352,7 @@ Set `readable` and/or `writable` to `true` to allow reads and/or writes on this
 socket (NOTE: Works only when `fd` is passed).
 About `allowHalfOpen`, refer to `createServer()` and `'end'` event.
 
-### socket.connect(port[, host]\[, connectListener])
+### socket.connect(port[, host][, connectListener])
 ### socket.connect(path[, connectListener])
 
 Opens the connection for a given socket. If `port` and `host` are given,
@@ -395,7 +395,7 @@ Users who experience large or growing `bufferSize` should attempt to
 Set the encoding for the socket as a Readable Stream. See
 [stream.setEncoding()][] for more information.
 
-### socket.write(data[, encoding]\[, callback])
+### socket.write(data[, encoding][, callback])
 
 Sends data on the socket. The second parameter specifies the encoding in the
 case of a string--it defaults to UTF8 encoding.
@@ -407,7 +407,7 @@ buffer. Returns `false` if all or part of the data was queued in user memory.
 The optional `callback` parameter will be executed when the data is finally
 written out - this may not be immediately.
 
-### socket.end([data]\[, encoding])
+### socket.end([data][, encoding])
 
 Half-closes the socket. i.e., it sends a FIN packet. It is possible the
 server will still send some data.
@@ -450,7 +450,7 @@ algorithm, they buffer data before sending it off. Setting `true` for
 `noDelay` will immediately fire off data each time `socket.write()` is called.
 `noDelay` defaults to `true`.
 
-### socket.setKeepAlive([enable]\[, initialDelay])
+### socket.setKeepAlive([enable][, initialDelay])
 
 Enable/disable keep-alive functionality, and optionally set the initial
 delay before the first keepalive probe is sent on an idle socket.
diff --git a/doc/api/path.markdown b/doc/api/path.markdown
index b9fb242..0e9a78b 100644
--- a/doc/api/path.markdown
+++ b/doc/api/path.markdown
@@ -22,7 +22,7 @@ Example:
     // returns
     '/foo/bar/baz/asdf'
 
-## path.join([path1]\[, path2]\[, ...])
+## path.join([path1][, path2][, ...])
 
 Join all arguments together and normalize the resulting path.
 
diff --git a/doc/api/querystring.markdown b/doc/api/querystring.markdown
index 884b287..e907c4e 100644
--- a/doc/api/querystring.markdown
+++ b/doc/api/querystring.markdown
@@ -7,7 +7,7 @@
 This module provides utilities for dealing with query strings.
 It provides the following methods:
 
-## querystring.stringify(obj[, sep]\[, eq]\[, options])
+## querystring.stringify(obj[, sep][, eq][, options])
 
 Serialize an object to a query string.
 Optionally override the default separator (`'&'`) and assignment (`'='`)
@@ -33,7 +33,7 @@ Example:
     // returns
     'w=%D6%D0%CE%C4&foo=bar'
 
-## querystring.parse(str[, sep]\[, eq]\[, options])
+## querystring.parse(str[, sep][, eq][, options])
 
 Deserialize a query string to an object.
 Optionally override the default separator (`'&'`) and assignment (`'='`)
diff --git a/doc/api/smalloc.markdown b/doc/api/smalloc.markdown
index 72e46ea..e407bb1 100644
--- a/doc/api/smalloc.markdown
+++ b/doc/api/smalloc.markdown
@@ -2,18 +2,20 @@
 
     Stability: 1 - Experimental
 
-## smalloc.alloc(length[, receiver][, type])
+## Class: smalloc
+
+Buffers are backed by a simple allocator that only handles the assignation of
+external raw memory. Smalloc exposes that functionality.
+
+### smalloc.alloc(length[, receiver][, type])
 
 * `length` {Number} `<= smalloc.kMaxLength`
-* `receiver` {Object}, Optional, Default: `new Object`
-* `type` {Enum}, Optional, Default: `Uint8`
+* `receiver` {Object} Default: `new Object`
+* `type` {Enum} Default: `Uint8`
 
 Returns `receiver` with allocated external array data. If no `receiver` is
 passed then a new Object will be created and returned.
 
-Buffers are backed by a simple allocator that only handles the assignation of
-external raw memory. Smalloc exposes that functionality.
-
 This can be used to create your own Buffer-like classes. No other properties are
 set, so the user will need to keep track of other necessary information (e.g.
 `length` of the allocation).
@@ -46,13 +48,13 @@ possible options are listed in `smalloc.Types`. Example usage:
 
     // { '0': 0, '1': 0.1, '2': 0.2 }
 
-## smalloc.copyOnto(source, sourceStart, dest, destStart, copyLength);
+### smalloc.copyOnto(source, sourceStart, dest, destStart, copyLength);
 
-* `source` Object with external array allocation
-* `sourceStart` Position to begin copying from
-* `dest` Object with external array allocation
-* `destStart` Position to begin copying onto
-* `copyLength` Length of copy
+* `source` {Object} with external array allocation
+* `sourceStart` {Number} Position to begin copying from
+* `dest` {Object} with external array allocation
+* `destStart` {Number} Position to begin copying onto
+* `copyLength` {Number} Length of copy
 
 Copy memory from one external array allocation to another. No arguments are
 optional, and any violation will throw.
@@ -75,7 +77,7 @@ optional, and any violation will throw.
 `copyOnto` automatically detects the length of the allocation internally, so no
 need to set any additional properties for this to work.
 
-## smalloc.dispose(obj)
+### smalloc.dispose(obj)
 
 * `obj` Object
 
@@ -107,17 +109,17 @@ careful. Cryptic errors may arise in applications that are difficult to trace.
 
 `dispose()` does not support Buffers, and will throw if passed.
 
-## smalloc.hasExternalData(obj)
+### smalloc.hasExternalData(obj)
 
 * `obj` {Object}
 
 Returns `true` if the `obj` has externally allocated memory.
 
-## smalloc.kMaxLength
+### smalloc.kMaxLength
 
 Size of maximum allocation. This is also applicable to Buffer creation.
 
-## smalloc.Types
+### smalloc.Types
 
 Enum of possible external array types. Contains:
 
diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown
index e79c2a2..ec8aabb 100644
--- a/doc/api/stream.markdown
+++ b/doc/api/stream.markdown
@@ -501,7 +501,7 @@ Examples of writable streams include:
 * [child process stdin](child_process.html#child_process_child_stdin)
 * [process.stdout][], [process.stderr][]
 
-#### writable.write(chunk[, encoding]\[, callback])
+#### writable.write(chunk[, encoding][, callback])
 
 * `chunk` {String | Buffer} The data to write
 * `encoding` {String} The encoding, if `chunk` is a String
@@ -564,7 +564,7 @@ Buffered data will be flushed either at `.uncork()` or at `.end()` call.
 
 Flush all data, buffered since `.cork()` call.
 
-#### writable.end([chunk]\[, encoding]\[, callback])
+#### writable.end([chunk][, encoding][, callback])
 
 * `chunk` {String | Buffer} Optional data to write
 * `encoding` {String} The encoding, if `chunk` is a String
diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown
index 0c484c2..92af0b6 100644
--- a/doc/api/timers.markdown
+++ b/doc/api/timers.markdown
@@ -5,7 +5,7 @@
 All of the timer functions are globals.  You do not need to `require()`
 this module in order to use them.
 
-## setTimeout(callback, delay[, arg]\[, ...])
+## setTimeout(callback, delay[, arg][, ...])
 
 To schedule execution of a one-time `callback` after `delay` milliseconds. Returns a
 `timeoutObject` for possible use with `clearTimeout()`. Optionally you can
@@ -20,7 +20,7 @@ be called as close as possible to the time specified.
 
 Prevents a timeout from triggering.
 
-## setInterval(callback, delay[, arg]\[, ...])
+## setInterval(callback, delay[, arg][, ...])
 
 To schedule the repeated execution of `callback` every `delay` milliseconds.
 Returns a `intervalObject` for possible use with `clearInterval()`. Optionally
@@ -47,7 +47,7 @@ If you had previously `unref()`d a timer you can call `ref()` to explicitly
 request the timer hold the program open. If the timer is already `ref`d calling
 `ref` again will have no effect.
 
-## setImmediate(callback[, arg]\[, ...])
+## setImmediate(callback[, arg][, ...])
 
 To schedule the "immediate" execution of `callback` after I/O events
 callbacks and before `setTimeout` and `setInterval` . Returns an
diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown
index 945b99e..7d9aada 100644
--- a/doc/api/tls.markdown
+++ b/doc/api/tls.markdown
@@ -286,7 +286,7 @@ You can test this server by connecting to it with `openssl s_client`:
 
 
 ## tls.connect(options[, callback])
-## tls.connect(port[, host]\[, options]\[, callback])
+## tls.connect(port[, host][, options][, callback])
 
 Creates a new client connection to the given `port` and `host` (old API) or
 `options.port` and `options.host`. (If `host` is omitted, it defaults to
@@ -455,7 +455,7 @@ publicly trusted list of CAs as given in
 <http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
 
 
-## tls.createSecurePair([context]\[, isServer]\[, requestCert]\[, rejectUnauthorized])
+## tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized])
 
     Stability: 0 - Deprecated. Use tls.TLSSocket instead.
 
@@ -594,7 +594,7 @@ NOTE: you may want to use some npm module like [asn1.js] to parse the
 certificates.
 
 
-### server.listen(port[, host]\[, callback])
+### server.listen(port[, host][, callback])
 
 Begin accepting connections on the specified `port` and `host`.  If the
 `host` is omitted, the server will accept connections directed to any
diff --git a/doc/api/url.markdown b/doc/api/url.markdown
index fc92bb7..e6a43f7 100644
--- a/doc/api/url.markdown
+++ b/doc/api/url.markdown
@@ -65,7 +65,7 @@ string will not be in the parsed object. Examples are shown for the URL
 
 The following methods are provided by the URL module:
 
-## url.parse(urlStr[, parseQueryString]\[, slashesDenoteHost])
+## url.parse(urlStr[, parseQueryString][, slashesDenoteHost])
 
 Take a URL string, and return an object.
 
diff --git a/doc/api/vm.markdown b/doc/api/vm.markdown
index 31f0f24..b145324 100644
--- a/doc/api/vm.markdown
+++ b/doc/api/vm.markdown
@@ -105,7 +105,7 @@ Note that running untrusted code is a tricky business requiring great care.
 separate process.
 
 
-## vm.runInNewContext(code[, sandbox]\[, options])
+## vm.runInNewContext(code[, sandbox][, options])
 
 `vm.runInNewContext` compiles `code`, contextifies `sandbox` if passed or
 creates a new contextified sandbox if it's omitted, and then runs the code with
@@ -238,7 +238,7 @@ Note that running untrusted code is a tricky business requiring great care.
 requires a separate process.
 
 
-### script.runInNewContext([sandbox]\[, options])
+### script.runInNewContext([sandbox][, options])
 
 Similar to `vm.runInNewContext` but a method of a precompiled `Script` object.
 `script.runInNewContext` contextifies `sandbox` if passed or creates a new
diff --git a/tools/doc/json.js b/tools/doc/json.js
index 2459bc2..9fdc3bc 100644
--- a/tools/doc/json.js
+++ b/tools/doc/json.js
@@ -287,13 +287,13 @@ function processList(section) {
 }
 
 
-// textRaw = "someobject.someMethod(a, [b=100], [c])"
+// textRaw = "someobject.someMethod(a[, b=100][, c])"
 function parseSignature(text, sig) {
   var params = text.match(paramExpr);
   if (!params) return;
   params = params[1];
-  // the ] is irrelevant. [ indicates optionalness.
-  params = params.replace(/\]/g, '');
+  // the [ is irrelevant. ] indicates optionalness.
+  params = params.replace(/\[/g, '');
   params = params.split(/,/)
   params.forEach(function(p, i, _) {
     p = p.trim();
@@ -302,9 +302,10 @@ function parseSignature(text, sig) {
     var optional = false;
     var def;
     // [foo] -> optional
-    if (p.charAt(0) === '[') {
+    if (p.charAt(p.length - 1) === ']') {
       optional = true;
-      p = p.substr(1);
+      p = p.substr(0, p.length - 1);
+      p = p.trim();
     }
     var eq = p.indexOf('=');
     if (eq !== -1) {
-- 
2.7.4