diff --git a/doc/api/addons.markdown b/doc/api/addons.markdown index 0e67ffc5af4cb3..f8a0c9efe4ef12 100644 --- a/doc/api/addons.markdown +++ b/doc/api/addons.markdown @@ -22,7 +22,7 @@ knowledge of several libraries: - Others. Look in `deps/` for what else is available. Node statically compiles all its dependencies into the executable. -When compiling your module, you don't need to worry about linking to +When compiling your module, you don’t need to worry about linking to any of these libraries. All of the following examples are available for @@ -31,7 +31,7 @@ used as a starting-point for your own Addon. ## Hello world -To get started let's make a small Addon which is the C++ equivalent of +To get started let’s make a small Addon which is the C++ equivalent of the following JavaScript code: module.exports.hello = function() { return 'world'; }; @@ -60,7 +60,7 @@ Note that all Node addons must export an initialization function: void Initialize (Handle exports); NODE_MODULE(module_name, Initialize) -There is no semi-colon after `NODE_MODULE` as it's not a function (see +There is no semi-colon after `NODE_MODULE` as it’s not a function (see `node.h`). The `module_name` needs to match the filename of the final binary (minus the @@ -106,7 +106,7 @@ Please see patterns below for further information or Below are some addon patterns to help you get started. Consult the online [v8 reference](http://izs.me/v8-docs/main.html) for help with the various v8 -calls, and v8's [Embedder's Guide](http://code.google.com/apis/v8/embed.html) +calls, and v8’s [Embedder’s Guide](http://code.google.com/apis/v8/embed.html) for an explanation of several concepts used such as handles, scopes, function templates, etc. @@ -183,7 +183,7 @@ You can test it with the following JavaScript snippet: ### Callbacks You can pass JavaScript functions to a C++ function and execute them from -there. Here's `addon.cc`: +there. Here’s `addon.cc`: // addon.cc #include @@ -346,7 +346,7 @@ Then in `myobject.h` make your wrapper inherit from `node::ObjectWrap`: #endif And in `myobject.cc` implement the various methods that you want to expose. -Here we expose the method `plusOne` by adding it to the constructor's +Here we expose the method `plusOne` by adding it to the constructor’s prototype: // myobject.cc @@ -426,7 +426,7 @@ explicitly instantiating them with the `new` operator in JavaScript, e.g. // instead of: // var obj = new addon.Object(); -Let's register our `createObject` method in `addon.cc`: +Let’s register our `createObject` method in `addon.cc`: // addon.cc #include @@ -564,7 +564,7 @@ Test it with: ### Passing wrapped objects around In addition to wrapping and returning C++ objects, you can pass them around -by unwrapping them with Node's `node::ObjectWrap::Unwrap` helper function. +by unwrapping them with Node’s `node::ObjectWrap::Unwrap` helper function. In the following `addon.cc` we introduce a function `add()` that can take on two `MyObject` objects: diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index 5d9cd9b9b7a1bb..29c44abd3f5df4 100644 --- a/doc/api/buffer.markdown +++ b/doc/api/buffer.markdown @@ -3,7 +3,7 @@ Stability: 3 - Stable Pure JavaScript is Unicode friendly but not nice to binary data. When -dealing with TCP streams or the file system, it's necessary to handle octet +dealing with TCP streams or the file system, it’s necessary to handle octet streams. Node has several strategies for manipulating, creating, and consuming octet streams. @@ -39,9 +39,9 @@ encoding method. Here are the different string encodings. Creating a typed array from a `Buffer` works with the following caveats: -1. The buffer's memory is copied, not shared. +1. The buffer’s memory is copied, not shared. -2. The buffer's memory is interpreted as an array, not a byte array. That is, +2. The buffer’s memory is interpreted as an array, not a byte array. That is, `new Uint32Array(new Buffer([1,2,3,4]))` creates a 4-element `Uint32Array` with elements `[1,2,3,4]`, not an `Uint32Array` with a single element `[0x1020304]` or `[0x4030201]`. @@ -463,7 +463,7 @@ Reads a signed 8 bit integer from the buffer at the specified offset. Set `noAssert` to true to skip validation of `offset`. This means that `offset` may be beyond the end of the buffer. Defaults to `false`. -Works as `buffer.readUInt8`, except buffer contents are treated as two's +Works as `buffer.readUInt8`, except buffer contents are treated as two’s complement signed values. ### buf.readInt16LE(offset[, noAssert]) @@ -479,7 +479,7 @@ specified endian format. Set `noAssert` to true to skip validation of `offset`. This means that `offset` may be beyond the end of the buffer. Defaults to `false`. -Works as `buffer.readUInt16*`, except buffer contents are treated as two's +Works as `buffer.readUInt16*`, except buffer contents are treated as two’s complement signed values. ### buf.readInt32LE(offset[, noAssert]) @@ -495,7 +495,7 @@ specified endian format. Set `noAssert` to true to skip validation of `offset`. This means that `offset` may be beyond the end of the buffer. Defaults to `false`. -Works as `buffer.readUInt32*`, except buffer contents are treated as two's +Works as `buffer.readUInt32*`, except buffer contents are treated as two’s complement signed values. ### buf.readFloatLE(offset[, noAssert]) @@ -654,7 +654,7 @@ that `value` may be too large for the specific function and `offset` may be beyond the end of the buffer leading to the values being silently dropped. This should not be used unless you are certain of correctness. Defaults to `false`. -Works as `buffer.writeUInt8`, except value is written out as a two's complement +Works as `buffer.writeUInt8`, except value is written out as a two’s complement signed integer into `buffer`. ### buf.writeInt16LE(value, offset[, noAssert]) @@ -672,7 +672,7 @@ that `value` may be too large for the specific function and `offset` may be beyond the end of the buffer leading to the values being silently dropped. This should not be used unless you are certain of correctness. Defaults to `false`. -Works as `buffer.writeUInt16*`, except value is written out as a two's +Works as `buffer.writeUInt16*`, except value is written out as a two’s complement signed integer into `buffer`. ### buf.writeInt32LE(value, offset[, noAssert]) @@ -690,7 +690,7 @@ that `value` may be too large for the specific function and `offset` may be beyond the end of the buffer leading to the values being silently dropped. This should not be used unless you are certain of correctness. Defaults to `false`. -Works as `buffer.writeUInt32*`, except value is written out as a two's +Works as `buffer.writeUInt32*`, except value is written out as a two’s complement signed integer into `buffer`. ### buf.writeFloatLE(value, offset[, noAssert]) diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown index 7db48829237d84..b9cece6bf56889 100644 --- a/doc/api/child_process.markdown +++ b/doc/api/child_process.markdown @@ -5,9 +5,9 @@ Node provides a tri-directional `popen(3)` facility through the `child_process` module. -It is possible to stream data through a child's `stdin`, `stdout`, and +It is possible to stream data through a child’s `stdin`, `stdout`, and `stderr` in a fully non-blocking way. (Note that some programs use -line-buffered I/O internally. That doesn't affect node.js but it means +line-buffered I/O internally. That doesn’t affect node.js but it means data you send to the child process may not be immediately consumed.) To create a child process use `require('child_process').spawn()` or @@ -94,7 +94,7 @@ Messages send by `.send(message, [sendHandle])` are obtained using the * {Stream object} -A `Writable Stream` that represents the child process's `stdin`. +A `Writable Stream` that represents the child process’s `stdin`. Closing this stream via `end()` often causes the child process to terminate. If the child stdio streams are shared with the parent, then this will @@ -104,7 +104,7 @@ not be set. * {Stream object} -A `Readable Stream` that represents the child process's `stdout`. +A `Readable Stream` that represents the child process’s `stdout`. If the child stdio streams are shared with the parent, then this will not be set. @@ -113,7 +113,7 @@ not be set. * {Stream object} -A `Readable Stream` that represents the child process's `stderr`. +A `Readable Stream` that represents the child process’s `stderr`. If the child stdio streams are shared with the parent, then this will not be set. @@ -134,7 +134,7 @@ Example: ### child.connected -* {Boolean} Set to false after `.disconnect' is called +* {Boolean} Set to false after `.disconnect` is called If `.connected` is false, it is no longer possible to send messages. @@ -159,7 +159,7 @@ May emit an `'error'` event when the signal cannot be delivered. Sending a signal to a child process that has already exited is not an error but may have unforeseen consequences: if the PID (the process ID) has been reassigned to another process, the signal will be delivered to that process instead. -What happens next is anyone's guess. +What happens next is anyone’s guess. Note that while the function is called `kill`, the signal delivered to the child process may not actually kill it. `kill` really just sends a signal @@ -292,7 +292,7 @@ gracefully once there are no other connections keeping it alive. After calling this method the `.connected` flag will be set to `false` in both the parent and child, and it is no longer possible to send messages. -The 'disconnect' event will be emitted when there are no messages in the process +The `disconnect` event will be emitted when there are no messages in the process of being received, most likely immediately. Note that you can also call `process.disconnect()` in the child process when the @@ -309,7 +309,7 @@ callback or returning an EventEmitter). * `args` {Array} List of string arguments * `options` {Object} * `cwd` {String} Current working directory of the child process - * `stdio` {Array|String} Child's stdio configuration. (See below) + * `stdio` {Array|String} Child’s stdio configuration. (See below) * `env` {Object} Environment key-value pairs * `detached` {Boolean} The child will be a process group leader. (See below) * `uid` {Number} Sets the user identity of the process. (See setuid(2).) @@ -391,7 +391,7 @@ Example of checking for failed exec: console.log('Failed to start child process.'); }); -The 'stdio' option to `child_process.spawn()` is an array where each +The `stdio` option to `child_process.spawn()` is an array where each index corresponds to a fd in the child. The value is one of the following: 1. `'pipe'` - Create a pipe between the child process and the parent process. @@ -408,9 +408,9 @@ index corresponds to a fd in the child. The value is one of the following: process.on('message'). 3. `'ignore'` - Do not set this file descriptor in the child. Note that Node will always open fd 0 - 2 for the processes it spawns. When any of these is - ignored node will open `/dev/null` and attach it to the child's fd. + ignored node will open `/dev/null` and attach it to the child’s fd. 4. `Stream` object - Share a readable or writable stream that refers to a tty, - file, socket, or a pipe with the child process. The stream's underlying + file, socket, or a pipe with the child process. The stream’s underlying file descriptor is duplicated in the child process to the fd that corresponds to the index in the `stdio` array. Note that the stream must have an underlying descriptor (file streams do not until the `'open'` @@ -433,7 +433,7 @@ Example: var spawn = require('child_process').spawn; - // Child will use parent's stdios + // Child will use parent’s stdios spawn('prg', [], { stdio: 'inherit' }); // Spawn child sharing only stderr @@ -449,7 +449,7 @@ after the parent exits. By default, the parent will wait for the detached child to exit. To prevent the parent from waiting for a given `child`, use the `child.unref()` method, -and the parent's event loop will not include the child in its reference count. +and the parent’s event loop will not include the child in its reference count. Example of detaching a long-running process and redirecting its output to a file: @@ -468,7 +468,7 @@ file: When using the `detached` option to start a long-running process, the process will not stay running in the background unless it is provided with a `stdio` -configuration that is not connected to the parent. If the parent's `stdio` is +configuration that is not connected to the parent. If the parent’s `stdio` is inherited, the child will remain attached to the controlling terminal. See also: `child_process.exec()` and `child_process.fork()` @@ -568,7 +568,7 @@ leaner than `child_process.exec`. It has the same options. (Default: `process.execArgv`) * `silent` {Boolean} If true, stdin, stdout, and stderr of the child will be piped to the parent, otherwise they will be inherited from the parent, see - the "pipe" and "inherit" options for `spawn()`'s `stdio` for more details + the "pipe" and "inherit" options for `spawn()`’s `stdio` for more details (default is false) * `uid` {Number} Sets the user identity of the process. (See setuid(2).) * `gid` {Number} Sets the group identity of the process. (See setgid(2).) @@ -606,7 +606,7 @@ configuration at startup. * `cwd` {String} Current working directory of the child process * `input` {String|Buffer} The value which will be passed as stdin to the spawned process - supplying this value will override `stdio[0]` - * `stdio` {Array} Child's stdio configuration. + * `stdio` {Array} Child’s stdio configuration. * `env` {Object} Environment key-value pairs * `uid` {Number} Sets the user identity of the process. (See setuid(2).) * `gid` {Number} Sets the group identity of the process. (See setgid(2).) @@ -624,9 +624,9 @@ configuration at startup. * `error` {Error} The error object if the child process failed or timed out `spawnSync` will not return until the child process has fully closed. When a -timeout has been encountered and `killSignal` is sent, the method won't return +timeout has been encountered and `killSignal` is sent, the method won’t return 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 +the `SIGTERM` signal and doesn’t exit, your process will wait until the child process has exited. ### child_process.execFileSync(command[, args][, options]) @@ -637,8 +637,8 @@ process has exited. * `cwd` {String} Current working directory of the child process * `input` {String|Buffer} The value which will be passed as stdin to the spawned process - supplying this value will override `stdio[0]` - * `stdio` {Array} Child's stdio configuration. (Default: 'pipe') - - `stderr` by default will be output to the parent process' stderr unless + * `stdio` {Array} Child’s stdio configuration. (Default: 'pipe') + - `stderr` by default will be output to the parent’s process stderr unless `stdio` is specified * `env` {Object} Environment key-value pairs * `uid` {Number} Sets the user identity of the process. (See setuid(2).) @@ -650,9 +650,9 @@ process has exited. * return: {Buffer|String} The stdout from the command `execFileSync` will not return until the child process has fully closed. When a -timeout has been encountered and `killSignal` is sent, the method won't return +timeout has been encountered and `killSignal` is sent, the method won’t return 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 +the `SIGTERM` signal and doesn’t exit, your process will wait until the child process has exited. If the process times out, or has a non-zero exit code, this method ***will*** @@ -667,8 +667,8 @@ throw. The `Error` object will contain the entire result from * `cwd` {String} Current working directory of the child process * `input` {String|Buffer} The value which will be passed as stdin to the spawned process - supplying this value will override `stdio[0]` - * `stdio` {Array} Child's stdio configuration. (Default: 'pipe') - - `stderr` by default will be output to the parent process' stderr unless + * `stdio` {Array} Child’s stdio configuration. (Default: 'pipe') + - `stderr` by default will be output to the parent’s process stderr unless `stdio` is specified * `env` {Object} Environment key-value pairs * `uid` {Number} Sets the user identity of the process. (See setuid(2).) @@ -680,9 +680,9 @@ throw. The `Error` object will contain the entire result from * return: {Buffer|String} The stdout from the command `execSync` will not return until the child process has fully closed. When a -timeout has been encountered and `killSignal` is sent, the method won't return +timeout has been encountered and `killSignal` is sent, the method won’t return 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 +the `SIGTERM` signal and doesn’t exit, your process will wait until the child process has exited. If the process times out, or has a non-zero exit code, this method ***will*** diff --git a/doc/api/cluster.markdown b/doc/api/cluster.markdown index f65e11c35921c0..080ba6fa268d01 100644 --- a/doc/api/cluster.markdown +++ b/doc/api/cluster.markdown @@ -78,11 +78,11 @@ node.js process and a cluster worker differs: 1. `server.listen({fd: 7})` Because the message is passed to the master, file descriptor 7 **in the parent** will be listened on, and the - handle passed to the worker, rather than listening to the worker's + handle passed to the worker, rather than listening to the worker’s idea of what the number 7 file descriptor references. 2. `server.listen(handle)` Listening on handles explicitly will cause the worker to use the supplied handle, rather than talk to the master - process. If the worker already has the handle, then it's presumed + process. If the worker already has the handle, then it’s presumed that you know what you are doing. 3. `server.listen(0)` Normally, this will cause servers to listen on a random port. However, in a cluster, each worker will receive the @@ -97,11 +97,11 @@ program such that it does not rely too heavily on in-memory data objects for things like sessions and login. Because workers are all separate processes, they can be killed or -re-spawned depending on your program's needs, without affecting other +re-spawned depending on your program’s needs, without affecting other workers. As long as there are some workers still alive, the server will continue to accept connections. Node does not automatically manage the number of workers for you, however. It is your responsibility to manage -the worker pool for your application's needs. +the worker pool for your application’s needs. ## cluster.schedulingPolicy @@ -126,7 +126,7 @@ values are `"rr"` and `"none"`. * `exec` {String} file path to worker file. (Default=`process.argv[1]`) * `args` {Array} string arguments passed to worker. (Default=`process.argv.slice(2)`) - * `silent` {Boolean} whether or not to send output to parent's stdio. + * `silent` {Boolean} whether or not to send output to parent’s stdio. (Default=`false`) * `uid` {Number} Sets the user identity of the process. (See setuid(2).) * `gid` {Number} Sets the group identity of the process. (See setgid(2).) @@ -266,7 +266,7 @@ If accuracy is important, use `cluster.settings`. * `exec` {String} file path to worker file. (Default=`process.argv[1]`) * `args` {Array} string arguments passed to worker. (Default=`process.argv.slice(2)`) - * `silent` {Boolean} whether or not to send output to parent's stdio. + * `silent` {Boolean} whether or not to send output to parent’s stdio. (Default=`false`) `setupMaster` is used to change the default 'fork' behavior. Once called, @@ -360,7 +360,7 @@ before last `'disconnect'` or `'exit'` event is emitted. }); Should you wish to reference a worker over a communication channel, using -the worker's unique id is the easiest way to find the worker. +the worker’s unique id is the easiest way to find the worker. socket.on('data', function(id) { var worker = cluster.workers[id]; @@ -515,13 +515,13 @@ the `disconnect` event has not been emitted after some time. ### worker.isDead() -This function returns `true` if the worker's process has terminated (either +This function returns `true` if the worker’s process has terminated (either because of exiting or being signaled). Otherwise, it returns `false`. ### worker.isConnected() This function returns `true` if the worker is connected to its master via its IPC -channel, `false` otherwise. A worker is connected to its master after it's been +channel, `false` otherwise. A worker is connected to its master after it’s been created. It is disconnected after the `disconnect` event is emitted. ### Event: 'message' diff --git a/doc/api/console.markdown b/doc/api/console.markdown index 46ab65fad36d36..b02f4756148639 100644 --- a/doc/api/console.markdown +++ b/doc/api/console.markdown @@ -11,7 +11,7 @@ provided by most web browsers, here the output is sent to stdout or stderr. The console functions are synchronous when the destination is a terminal or a file (to avoid lost messages in case of premature exit) and asynchronous -when it's a pipe (to avoid blocking for long periods of time). +when it’s a pipe (to avoid blocking for long periods of time). That is, in the following example, stdout is non-blocking while stderr is blocking: @@ -52,7 +52,7 @@ Uses `util.inspect` on `obj` and prints resulting string to stdout. This functio bypasses any custom `inspect()` function on `obj`. An optional *options* object may be passed that alters certain aspects of the formatted string: -- `showHidden` - if `true` then the object's non-enumerable properties will be +- `showHidden` - if `true` then the object’s non-enumerable properties will be shown too. Defaults to `false`. - `depth` - tells `inspect` how many times to recurse while formatting the diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index b6dcf46124a7bc..59bc461d4a1153 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -8,7 +8,7 @@ Use `require('crypto')` to access this module. The crypto module offers a way of encapsulating secure credentials to be used as part of a secure HTTPS net or http connection. -It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, +It also offers a set of wrappers for OpenSSL’s hash, hmac, cipher, decipher, sign and verify methods. @@ -16,7 +16,7 @@ decipher, sign and verify methods. Load and set engine for some/all OpenSSL functions (selected by flags). -`engine` could be either an id or a path to the to the engine's shared library. +`engine` could be either an id or a path to the to the engine’s shared library. `flags` is optional and has `ENGINE_METHOD_ALL` value by default. It could take one of or mix of following flags (defined in `constants` module): @@ -241,7 +241,7 @@ called. You can disable automatic padding of the input data to block size. If `auto_padding` is false, the length of the entire input data must be a -multiple of the cipher's block size or `final` will fail. Useful for +multiple of the cipher’s block size or `final` will fail. Useful for non-standard padding, e.g. using `0x0` instead of PKCS padding. You must call this before `cipher.final`. @@ -304,7 +304,7 @@ called. You can disable auto padding if the data has been encrypted without standard block padding to prevent `decipher.final` from checking and -removing it. Can only work if the input data's length is a multiple of +removing it. Can only work if the input data’s length is a multiple of the ciphers block size. You must call this before streaming data to `decipher.update`. @@ -445,7 +445,7 @@ or `'base64'`. If no encoding is provided, then a buffer is returned. ### 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 +party’s public key and returns the computed shared secret. Supplied key is interpreted using specified `input_encoding`, and secret is encoded using specified `output_encoding`. Encodings can be `'binary'`, `'hex'`, or `'base64'`. If the input encoding is not @@ -498,7 +498,7 @@ supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in [RFC interface of objects created by [crypto.createDiffieHellman()][] above, but will not allow to change the keys (with [diffieHellman.setPublicKey()][] for example). The advantage of using -this routine is that the parties don't have to generate nor exchange +this routine is that the parties don’t have to generate nor exchange group modulus beforehand, saving both processor and communication time. @@ -544,7 +544,7 @@ then a buffer is returned. ### 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 +party’s public key and returns the computed shared secret. Supplied key is interpreted using specified `input_encoding`, and secret is encoded using specified `output_encoding`. Encodings can be `'binary'`, `'hex'`, or `'base64'`. If the input encoding is not @@ -724,7 +724,7 @@ The Crypto module was added to Node before there was the concept of a unified Stream API, and before there were Buffer objects for handling binary data. -As such, the streaming classes don't have the typical methods found on +As such, the streaming classes don’t have the typical methods found on other Node classes, and many methods accepted and returned Binary-encoded strings by default rather than Buffers. This was changed to use Buffers by default instead. @@ -735,16 +735,16 @@ For example, if you currently use the default arguments to the Sign class, and then pass the results to the Verify class, without ever inspecting the data, then it will continue to work as before. Where you once got a binary string and then presented the binary string to -the Verify object, you'll now get a Buffer, and present the Buffer to +the Verify object, you’ll now get a Buffer, and present the Buffer to the Verify object. However, if you were doing things with the string data that will not work properly on Buffers (such as, concatenating them, storing in databases, etc.), or you are passing binary strings to the crypto functions without an encoding argument, then you will need to start -providing encoding arguments to specify which encoding you'd like to +providing encoding arguments to specify which encoding you’d like to use. To switch to the previous style of using binary strings by -default, set the `crypto.DEFAULT_ENCODING` field to 'binary'. Note +default, set the `crypto.DEFAULT_ENCODING` field to `'binary'`. Note that new programs will probably expect buffers, so only use this as a temporary measure. diff --git a/doc/api/debugger.markdown b/doc/api/debugger.markdown index b4863a81a27c5a..d2e53b09e94d22 100644 --- a/doc/api/debugger.markdown +++ b/doc/api/debugger.markdown @@ -18,7 +18,7 @@ Node has a built-in client for this debugger. To use this, start Node with the 3 debugger; debug> -Node's debugger client doesn't support the full range of commands, but +Node’s debugger client doesn’t support the full range of commands, but simple step and inspection is possible. By putting the statement `debugger;` into the source code of your script, you will enable a breakpoint. @@ -82,7 +82,7 @@ to come. Type `help` to see others. You can watch expression and variable values while debugging your code. On every breakpoint each expression from the watchers list will be evaluated -in the current context and displayed just before the breakpoint's source code +in the current context and displayed just before the breakpoint’s source code listing. To start watching an expression, type `watch("my_expression")`. `watchers` @@ -110,7 +110,7 @@ script.js * `clearBreakpoint`, `cb(...)` - Clear breakpoint It is also possible to set a breakpoint in a file (module) that -isn't loaded yet: +isn’t loaded yet: % ./node debug test/fixtures/break-in-module/main.js < debugger listening on port 5858 @@ -142,18 +142,18 @@ after) * `unwatch(expr)` - Remove expression from watch list * `watchers` - List all watchers and their values (automatically listed on each breakpoint) -* `repl` - Open debugger's repl for evaluation in debugging script's context +* `repl` - Open debugger’s repl for evaluation in debugging script’s context ### Execution control -* `run` - Run script (automatically runs on debugger's start) +* `run` - Run script (automatically runs on debugger’s start) * `restart` - Restart script * `kill` - Kill script ### Various * `scripts` - List all loaded scripts -* `version` - Display v8's version +* `version` - Display v8’s version ## Advanced Usage diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown index 09bacaf098c117..d02e2dcd189116 100644 --- a/doc/api/dgram.markdown +++ b/doc/api/dgram.markdown @@ -68,7 +68,7 @@ should be created via `dgram.createSocket(...)` * `rinfo` Object. Remote address information Emitted when a new datagram is available on a socket. `msg` is a `Buffer` and -`rinfo` is an object with the sender's address information: +`rinfo` is an object with the sender’s address information: socket.on('message', function(msg, rinfo) { console.log('Received %d bytes from %s:%d\n', @@ -105,14 +105,14 @@ may be supplied for the `address` parameter, and it will be resolved with DNS. If the address is omitted or is an empty string, `'0.0.0.0'` or `'::0'` is used instead. Depending on the network configuration, those defaults may or may not -work; it's best to be explicit about the destination address. +work; it’s best to be explicit about the destination address. If the socket has not been previously bound with a call to `bind`, it gets assigned a random port number and is bound to the "all interfaces" address (`'0.0.0.0'` for `udp4` sockets, `'::0'` for `udp6` sockets.) An optional callback may be specified to detect DNS errors or for determining -when it's safe to reuse the `buf` object. Note that DNS lookups delay the time +when it’s safe to reuse the `buf` object. Note that DNS lookups delay the time to send for at least one tick. The only way to know for sure that the datagram has been sent is by using a callback. @@ -151,9 +151,9 @@ and on the `Payload Length` field size. The value of `68` octets is very small, since most current link layer technologies have a minimum `MTU` of `1500` (like Ethernet). -Note that it's impossible to know in advance the MTU of each link through which +Note that it’s impossible to know in advance the MTU of each link through which a packet might travel, and that generally sending a datagram greater than -the (receiver) `MTU` won't work (the packet gets silently dropped, without +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]) @@ -242,7 +242,7 @@ this object will contain `address` , `family` and `port`. * `flag` Boolean Sets or clears the `SO_BROADCAST` socket option. When this option is set, UDP packets -may be sent to a local interface's broadcast address. +may be sent to a local interface’s broadcast address. ### socket.setTTL(ttl) @@ -308,5 +308,5 @@ active socket in the event system. If the socket is already `unref`d calling ### socket.ref() Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not* -let the program exit if it's the only socket left (the default behavior). If +let the program exit if it’s the only socket left (the default behavior). If the socket is `ref`d calling `ref` again will have no effect. diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown index d080d666186ead..69235ccdc02225 100644 --- a/doc/api/dns.markdown +++ b/doc/api/dns.markdown @@ -188,7 +188,7 @@ Given an array of IP addresses as strings, set them as the servers to use for resolving If you specify a port with the address it will be stripped, as the underlying -library doesn't support that. +library doesn’t support that. This will throw if you pass invalid input. diff --git a/doc/api/documentation.markdown b/doc/api/documentation.markdown index 6ef71896b1075c..0dab4fb9f4cfce 100644 --- a/doc/api/documentation.markdown +++ b/doc/api/documentation.markdown @@ -16,7 +16,7 @@ experimental, and added for the benefit of IDEs and other utilities that wish to do programmatic things with the documentation. Every `.html` and `.json` file is generated based on the corresponding -`.markdown` file in the `doc/api/` folder in node's source tree. The +`.markdown` file in the `doc/api/` folder in node’s source tree. The documentation is generated using the `tools/doc/generate.js` program. The HTML template is located at `doc/template.html`. @@ -24,7 +24,7 @@ The HTML template is located at `doc/template.html`. -Throughout the documentation, you will see indications of a section's +Throughout the documentation, you will see indications of a section’s stability. The Node.js API is still somewhat changing, and as it matures, certain parts are more reliable than others. Some are so proven, and so relied upon, that they are unlikely to ever change at diff --git a/doc/api/domain.markdown b/doc/api/domain.markdown index 123020f14a9f1d..93a667e01ef128 100644 --- a/doc/api/domain.markdown +++ b/doc/api/domain.markdown @@ -9,7 +9,7 @@ will be notified, rather than losing the context of the error in the `process.on('uncaughtException')` handler, or causing the program to exit immediately with an error code. -## Warning: Don't Ignore Errors! +## Warning: Don’t Ignore Errors! @@ -66,7 +66,7 @@ var cluster = require('cluster'); var PORT = +process.env.PORT || 1337; if (cluster.isMaster) { - // In real life, you'd probably use more than just 2 workers, + // In real life, you’d probably use more than just 2 workers, // and perhaps not put the master and worker in the same file. // // You can also of course get a bit fancier about logging, and @@ -101,9 +101,9 @@ if (cluster.isMaster) { d.on('error', function(er) { console.error('error', er.stack); - // Note: we're in dangerous territory! + // Note: we’re in dangerous territory! // By definition, something unexpected occurred, - // which we probably didn't want. + // which we probably didn’t want. // Anything can happen now! Be very careful! try { @@ -111,13 +111,13 @@ if (cluster.isMaster) { var killtimer = setTimeout(function() { process.exit(1); }, 30000); - // But don't keep the process open just for that! + // But don’t keep the process open just for that! killtimer.unref(); // stop taking new requests. server.close(); - // Let the master know we're dead. This will trigger a + // Let the master know we’re dead. This will trigger a // 'disconnect' in the cluster master, and then it will fork // a new worker. cluster.worker.disconnect(); @@ -146,8 +146,8 @@ if (cluster.isMaster) { server.listen(PORT); } -// This part isn't important. Just an example routing thing. -// You'd put your fancy application logic here. +// This part isn’t important. Just an example routing thing. +// You’d put your fancy application logic here. function handleRequest(req, res) { switch(req.url) { case '/error': @@ -200,7 +200,7 @@ If you *want* to nest Domain objects as children of a parent Domain, then you must explicitly add them. Implicit binding routes thrown errors and `'error'` events to the -Domain's `error` event, but does not register the EventEmitter on the +Domain’s `error` event, but does not register the EventEmitter on the Domain, so `domain.dispose()` will not shut down the EventEmitter. Implicit binding only takes care of thrown errors and `'error'` events. @@ -228,7 +228,7 @@ serverDomain.run(function() { // server is created in the scope of serverDomain http.createServer(function(req, res) { // req and res are also created in the scope of serverDomain - // however, we'd prefer to have a separate domain for each request. + // however, we’d prefer to have a separate domain for each request. // create it first thing, and add req and res to it. var reqd = domain.create(); reqd.add(req); @@ -305,7 +305,7 @@ to the domain. Explicitly adds an emitter to the domain. If any event handlers called by the emitter throw an error, or if the emitter emits an `error` event, it -will be routed to the domain's `error` event, just like with implicit +will be routed to the domain’s `error` event, just like with implicit binding. This also works with timers that are returned from `setInterval` and @@ -329,7 +329,7 @@ specified emitter. The returned function will be a wrapper around the supplied callback function. When the returned function is called, any errors that are -thrown will be routed to the domain's `error` event. +thrown will be routed to the domain’s `error` event. #### Example @@ -404,7 +404,7 @@ without setting the domain. The `exit` method exits the current domain, popping it off the domain stack. Any time execution is going to switch to the context of a different chain of -asynchronous calls, it's important to ensure that the current domain is exited. +asynchronous calls, it’s important to ensure that the current domain is exited. The call to `exit` delimits either the end of or an interruption to the chain of asynchronous calls and I/O operations bound to a domain. diff --git a/doc/api/events.markdown b/doc/api/events.markdown index 895debba026859..6e33e572a70cee 100644 --- a/doc/api/events.markdown +++ b/doc/api/events.markdown @@ -10,7 +10,7 @@ opened. All objects which emit events are instances of `events.EventEmitter`. You can access this module by doing: `require("events");` Typically, event names are represented by a camel-cased string, however, -there aren't any strict restrictions on that, as any string will be accepted. +there aren’t any strict restrictions on that, as any string will be accepted. Functions can then be attached to objects, to be executed when an event is emitted. These functions are called _listeners_. Inside a listener @@ -69,9 +69,9 @@ Returns emitter, so calls can be chained. ### emitter.removeAllListeners([event]) -Removes all listeners, or those of the specified event. It's not a good idea to -remove listeners that were added elsewhere in the code, especially when it's on -an emitter that you didn't create (e.g. sockets or file streams). +Removes all listeners, or those of the specified event. It’s not a good idea to +remove listeners that were added elsewhere in the code, especially when it’s on +an emitter that you didn’t create (e.g. sockets or file streams). Returns emitter, so calls can be chained. diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown index c6bfa2456bc17d..05be4e21dbfe2f 100644 --- a/doc/api/fs.markdown +++ b/doc/api/fs.markdown @@ -228,7 +228,7 @@ linkString)`. ## fs.readlinkSync(path) -Synchronous readlink(2). Returns the symbolic link's string value. +Synchronous readlink(2). Returns the symbolic link’s string value. ## fs.realpath(path[, cache], callback) @@ -311,10 +311,10 @@ An exception occurs if the file does not exist. This is primarily useful for opening files on NFS mounts as it allows you to skip the potentially stale local cache. It has a very real impact on I/O - performance so don't use this flag unless you need it. + performance so don’t use this flag unless you need it. - Note that this doesn't turn `fs.open()` into a synchronous blocking call. - If that's what you want then you should be using `fs.openSync()` + Note that this doesn’t turn `fs.open()` into a synchronous blocking call. + If that’s what you want then you should be using `fs.openSync()` * `'rs+'` - Open file for reading and writing, telling the OS to open it synchronously. See notes for `'rs'` about using this with caution. @@ -349,7 +349,7 @@ created. On POSIX systems, `path` is considered to exist even if it is a symlink to a non-existent file. The exclusive flag may or may not work with network file systems. -On Linux, positional writes don't work when the file is opened in append mode. +On Linux, positional writes don’t work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file. @@ -394,7 +394,7 @@ Note that it is unsafe to use `fs.write` multiple times on the same file without waiting for the callback. For this scenario, `fs.createWriteStream` is strongly recommended. -On Linux, positional writes don't work when the file is opened in append mode. +On Linux, positional writes don’t work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file. @@ -422,7 +422,7 @@ Note that it is unsafe to use `fs.write` multiple times on the same file without waiting for the callback. For this scenario, `fs.createWriteStream` is strongly recommended. -On Linux, positional writes don't work when the file is opened in append mode. +On Linux, positional writes don’t work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file. @@ -614,7 +614,7 @@ to be notified of filesystem changes. If the underlying functionality is not available for some reason, then `fs.watch` will not be able to function. For example, watching files or -directories on network file systems (NFS, SMB, etc.) often doesn't work +directories on network file systems (NFS, SMB, etc.) often doesn’t work reliably or at all. You can still use `fs.watchFile`, which uses stat polling, but it is slower and @@ -625,9 +625,9 @@ less reliable. Providing `filename` argument in the callback is not supported -on every platform (currently it's only supported on Linux and Windows). Even +on every platform (currently it’s only supported on Linux and Windows). Even on supported platforms `filename` is not always guaranteed to be provided. -Therefore, don't assume that `filename` argument is always provided in the +Therefore, don’t assume that `filename` argument is always provided in the callback, and have some fallback logic if it is null. fs.watch('somedir', function (event, filename) { @@ -654,7 +654,7 @@ There should almost never be a reason to use it in your own code. In particular, checking if a file exists before opening it is an anti-pattern that leaves you vulnerable to race conditions: another process may remove the file between the calls to `fs.exists()` and `fs.open()`. Just open the file -and handle the error when it's not there. +and handle the error when it’s not there. ## fs.existsSync(path) @@ -745,9 +745,9 @@ Returns a new ReadStream object (See `Readable Stream`). the file instead of the entire file. Both `start` and `end` are inclusive and start at 0. The `encoding` can be `'utf8'`, `'ascii'`, or `'base64'`. -If `autoClose` is false, then the file descriptor won't be closed, even if -there's an error. It is your responsibility to close it and make sure -there's no file descriptor leak. If `autoClose` is set to true (default +If `autoClose` is false, then the file descriptor won’t be closed, even if +there’s an error. It is your responsibility to close it and make sure +there’s no file descriptor leak. If `autoClose` is set to true (default behavior), on `error` or `end` the file descriptor will be closed automatically. @@ -764,7 +764,7 @@ An example to read the last 10 bytes of a file which is 100 bytes long: * `fd` {Integer} file descriptor used by the ReadStream. -Emitted when the ReadStream's file is opened. +Emitted when the ReadStream’s file is opened. ## fs.createWriteStream(path[, options]) @@ -790,7 +790,7 @@ default mode `w`. * `fd` {Integer} file descriptor used by the WriteStream. -Emitted when the WriteStream's file is opened. +Emitted when the WriteStream’s file is opened. ### file.bytesWritten diff --git a/doc/api/globals.markdown b/doc/api/globals.markdown index 4fb8613382303d..334fb0468def1a 100644 --- a/doc/api/globals.markdown +++ b/doc/api/globals.markdown @@ -2,7 +2,7 @@ -These objects are available in all modules. Some of these objects aren't +These objects are available in all modules. Some of these objects aren’t actually in the global scope but in the module scope - this will be noted. ## global @@ -12,7 +12,7 @@ actually in the global scope but in the module scope - this will be noted. * {Object} The global namespace object. In browsers, the top-level scope is the global scope. That means that in -browsers if you're in the global scope `var something` will define a global +browsers if you’re in the global scope `var something` will define a global variable. In Node this is different. The top-level scope is not the global scope; `var something` inside a Node module will be local to that module. @@ -46,7 +46,7 @@ Used to handle binary data. See the [buffer section][] * {Function} -To require modules. See the [Modules][] section. `require` isn't actually a +To require modules. See the [Modules][] section. `require` isn’t actually a global but rather local to each module. ### require.resolve() @@ -99,7 +99,7 @@ Example: running `node example.js` from `/Users/mjr` console.log(__filename); // /Users/mjr/example.js -`__filename` isn't actually a global but rather local to each module. +`__filename` isn’t actually a global but rather local to each module. ## __dirname @@ -114,7 +114,7 @@ Example: running `node example.js` from `/Users/mjr` console.log(__dirname); // /Users/mjr -`__dirname` isn't actually a global but rather local to each module. +`__dirname` isn’t actually a global but rather local to each module. ## module @@ -127,7 +127,7 @@ A reference to the current module. In particular `module.exports` is used for defining what a module exports and makes available through `require()`. -`module` isn't actually a global but rather local to each module. +`module` isn’t actually a global but rather local to each module. See the [module system documentation][] for more information. @@ -139,7 +139,7 @@ A reference to the `module.exports` that is shorter to type. See [module system documentation][] for details on when to use `exports` and when to use `module.exports`. -`exports` isn't actually a global but rather local to each module. +`exports` isn’t actually a global but rather local to each module. See the [module system documentation][] for more information. @@ -151,7 +151,7 @@ Run callback `cb` after *at least* `ms` milliseconds. The actual delay depends on external factors like OS timer granularity and system load. The timeout must be in the range of 1-2,147,483,647 inclusive. If the value is -outside that range, it's changed to 1 millisecond. Broadly speaking, a timer +outside that range, it’s changed to 1 millisecond. Broadly speaking, a timer cannot span more than 24.8 days. Returns an opaque value that represents the timer. @@ -165,10 +165,10 @@ not execute. Run callback `cb` repeatedly every `ms` milliseconds. Note that the actual interval may vary, depending on external factors like OS timer granularity and -system load. It's never less than `ms` but it may be longer. +system load. It’s never less than `ms` but it may be longer. The interval must be in the range of 1-2,147,483,647 inclusive. If the value is -outside that range, it's changed to 1 millisecond. Broadly speaking, a timer +outside that range, it’s changed to 1 millisecond. Broadly speaking, a timer cannot span more than 24.8 days. Returns an opaque value that represents the timer. diff --git a/doc/api/http.markdown b/doc/api/http.markdown index 827bba62631219..945caad11bac5b 100644 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -20,7 +20,7 @@ HTTP message headers are represented by an object like this: Keys are lowercased. Values are not modified. -In order to support the full spectrum of possible HTTP applications, Node's +In order to support the full spectrum of possible HTTP applications, Node’s HTTP API is very low-level. It deals with stream handling and message parsing only. It parses a message into headers and body but it does not parse the actual headers or the body. @@ -104,7 +104,7 @@ Emitted when the server closes. `function (request, response) { }` Emitted each time a request with an http Expect: 100-continue is received. -If this event isn't listened for, the server will automatically respond +If this event isn’t listened for, the server will automatically respond with a 100 Continue as appropriate. Handling this event involves calling [response.writeContinue()][] if the client @@ -119,7 +119,7 @@ not be emitted. `function (request, socket, head) { }` -Emitted each time a client requests a http CONNECT method. If this event isn't +Emitted each time a client requests a http CONNECT method. If this event isn’t listened for, then clients requesting a CONNECT method will have their connections closed. @@ -129,7 +129,7 @@ connections closed. * `head` is an instance of Buffer, the first packet of the tunneling stream, this may be empty. -After this event is emitted, the request's socket will not have a `data` +After this event is emitted, the request’s socket will not have a `data` event listener, meaning you will need to bind to it in order to handle data sent to the server on that socket. @@ -137,7 +137,7 @@ sent to the server on that socket. `function (request, socket, head) { }` -Emitted each time a client requests a http upgrade. If this event isn't +Emitted each time a client requests a http upgrade. If this event isn’t listened for, then clients requesting an upgrade will have their connections closed. @@ -147,7 +147,7 @@ closed. * `head` is an instance of Buffer, the first packet of the upgraded stream, this may be empty. -After this event is emitted, the request's socket will not have a `data` +After this event is emitted, the request’s socket will not have a `data` event listener, meaning you will need to bind to it in order to handle data sent to the server on that socket. @@ -225,9 +225,9 @@ occurs. If there is a `'timeout'` event listener on the Server object, then it will be called with the timed-out socket as an argument. -By default, the Server's timeout value is 2 minutes, and sockets are +By default, the Server’s timeout value is 2 minutes, and sockets are destroyed automatically if they time out. However, if you assign a -callback to the Server's `'timeout'` event, then you are responsible +callback to the Server’s `'timeout'` event, then you are responsible for handling socket timeouts. ### server.timeout @@ -307,13 +307,13 @@ which has been transmitted are equal or not. * `msecs` {Number} * `callback` {Function} -Sets the Socket's timeout value to `msecs`. If a callback is +Sets the Socket’s timeout value to `msecs`. If a callback is provided, then it is added as a listener on the `'timeout'` event on the response object. If no `'timeout'` listener is added to the request, the response, or the server, then sockets are destroyed when they time out. If you -assign a handler on the request, the response, or the server's +assign a handler on the request, the response, or the server’s `'timeout'` events, then it is your responsibility to handle timed out sockets. @@ -372,7 +372,7 @@ in responses. ### response.getHeader(name) -Reads out a header that's already been queued but not sent to the client. Note +Reads out a header that’s already been queued but not sent to the client. Note that the name is case insensitive. This can only be called before headers get implicitly flushed. @@ -382,7 +382,7 @@ Example: ### response.removeHeader(name) -Removes a header that's queued for implicit sending. +Removes a header that’s queued for implicit sending. Example: @@ -406,7 +406,7 @@ higher-level multi-part body encodings that may be used. The first time `response.write()` is called, it will send the buffered header information and the first body to the client. The second time -`response.write()` is called, Node assumes you're going to be streaming +`response.write()` is called, Node assumes you’re going to be streaming data, and sends that separately. That is, the response is buffered up to the first chunk of body. @@ -522,7 +522,7 @@ Example: req.end(); Note that in the example `req.end()` was called. With `http.request()` one -must always call `req.end()` to signify that you're done with the request - +must always call `req.end()` to signify that you’re done with the request - even if there is no data being written to the request body. If any error is encountered during the request (be that with DNS resolution, @@ -566,7 +566,7 @@ requests. The HTTP Agent also defaults client requests to using Connection:keep-alive. If no pending HTTP requests are waiting on a -socket to become free the socket is closed. This means that Node's +socket to become free the socket is closed. This means that Node’s pool has the benefit of keep-alive when under load but still does not require developers to manually close the HTTP clients using KeepAlive. @@ -580,9 +580,9 @@ still a good idea to explicitly [`destroy()`](#http_agent_destroy) KeepAlive agents when they are no longer in use, so that the Sockets will be shut down. -Sockets are removed from the agent's pool when the socket emits either +Sockets are removed from the agent’s pool when the socket emits either a "close" event or a special "agentRemove" event. This means that if -you intend to keep one HTTP request open for a long time and don't +you intend to keep one HTTP request open for a long time and don’t want it to stay in the pool you can do something along the lines of: http.get(options, function(res) { @@ -737,7 +737,7 @@ Emitted after a socket is assigned to this request. `function (response, socket, head) { }` Emitted each time a server responds to a request with a CONNECT method. If this -event isn't being listened for, clients receiving a CONNECT method will have +event isn’t being listened for, clients receiving a CONNECT method will have their connections closed. A client server pair that show you how to listen for the `connect` event. @@ -800,7 +800,7 @@ A client server pair that show you how to listen for the `connect` event. `function (response, socket, head) { }` Emitted each time a server responds to a request with an upgrade. If this -event isn't being listened for, clients receiving an upgrade header will have +event isn’t being listened for, clients receiving an upgrade header will have their connections closed. A client server pair that show you how to listen for the `upgrade` event. @@ -860,8 +860,8 @@ For efficiency reasons, node.js normally buffers the request headers until you call `request.end()` or write the first chunk of request data. It then tries hard to pack the request headers and data into a single TCP packet. -That's usually what you want (it saves a TCP round-trip) but not when the first -data isn't sent until possibly much later. `request.flush()` lets you bypass +That’s usually what you want (it saves a TCP round-trip) but not when the first +data isn’t sent until possibly much later. `request.flush()` lets you bypass the optimization and kickstart the request. ### request.write(chunk[, encoding]) @@ -1043,7 +1043,7 @@ The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server The `net.Socket` object associated with the connection. With HTTPS support, use request.connection.verifyPeer() and -request.connection.getPeerCertificate() to obtain the client's +request.connection.getPeerCertificate() to obtain the client’s authentication details. diff --git a/doc/api/modules.markdown b/doc/api/modules.markdown index 55d6accdf99e99..959c328116a467 100644 --- a/doc/api/modules.markdown +++ b/doc/api/modules.markdown @@ -33,7 +33,7 @@ you can add them to the special `exports` object. Variables local to the module will be private, as though the module was wrapped in a function. In this example the variable `PI` is private to `circle.js`. -If you want the root of your module's export to be a function (such as a +If you want the root of your module’s export to be a function (such as a constructor) or if you want to export a complete object in one assignment instead of building it one property at a time, assign it to `module.exports` instead of `exports`. @@ -97,7 +97,7 @@ loop, an **unfinished copy** of the `a.js` exports object is returned to the `b.js` module. `b.js` then finishes loading, and its `exports` object is provided to the `a.js` module. -By the time `main.js` has loaded both modules, they're both finished. +By the time `main.js` has loaded both modules, they’re both finished. The output of this program would thus be: $ node main.js @@ -120,7 +120,7 @@ plan accordingly. Node has several modules compiled into the binary. These modules are described in greater detail elsewhere in this documentation. -The core modules are defined in node's source in the `lib/` folder. +The core modules are defined in node’s source in the `lib/` folder. Core modules are always preferentially loaded if their identifier is passed to `require()`. For instance, `require('http')` will always @@ -195,7 +195,7 @@ If this was in a folder at `./some-library`, then `require('./some-library')` would attempt to load `./some-library/lib/some-library.js`. -This is the extent of Node's awareness of package.json files. +This is the extent of Node’s awareness of package.json files. If there is no package.json file present in the directory, then node will attempt to load an `index.js` or `index.node` file out of that @@ -240,7 +240,7 @@ would resolve to different files. In each module, the `module` free variable is a reference to the object representing the current module. For convenience, `module.exports` is -also accessible via the `exports` module-global. `module` isn't actually +also accessible via the `exports` module-global. `module` isn’t actually a global but rather local to each module. ### module.exports @@ -320,7 +320,7 @@ The `module.require` method provides a way to load a module as if Note that in order to do this, you must get a reference to the `module` object. Since `require()` returns the `module.exports`, and the `module` is -typically *only* available within a specific module's code, it must be +typically *only* available within a specific module’s code, it must be explicitly exported in order to be used. @@ -429,7 +429,7 @@ Additionally, node will search in the following locations: * 2: `$HOME/.node_libraries` * 3: `$PREFIX/lib/node` -Where `$HOME` is the user's home directory, and `$PREFIX` is node's +Where `$HOME` is the user’s home directory, and `$PREFIX` is node’s configured `node_prefix`. These are mostly for historic reasons. You are highly encouraged to @@ -457,14 +457,14 @@ by checking `require.main.filename`. -The semantics of Node's `require()` function were designed to be general +The semantics of Node’s `require()` function were designed to be general enough to support a number of sane directory structures. Package manager programs such as `dpkg`, `rpm`, and `npm` will hopefully find it possible to build native packages from Node modules without modification. Below we give a suggested directory structure that could work: -Let's say that we wanted to have the folder at +Let’s say that we wanted to have the folder at `/usr/lib/node//` hold the contents of a specific version of a package. @@ -492,7 +492,7 @@ that it can use. When the code in the `foo` package does `require('bar')`, it will get the version that is symlinked into `/usr/lib/node/foo/1.2.3/node_modules/bar`. -Then, when the code in the `bar` package calls `require('quux')`, it'll get +Then, when the code in the `bar` package calls `require('quux')`, it’ll get the version that is symlinked into `/usr/lib/node/bar/4.3.2/node_modules/quux`. diff --git a/doc/api/net.markdown b/doc/api/net.markdown index 816050ae86e91d..2343612418b523 100644 --- a/doc/api/net.markdown +++ b/doc/api/net.markdown @@ -18,7 +18,7 @@ automatically set as a listener for the ['connection'][] event. pauseOnConnect: false } -If `allowHalfOpen` is `true`, then the socket won't automatically send a FIN +If `allowHalfOpen` is `true`, then the socket won’t automatically send a FIN packet when the other end of the socket sends a FIN packet. The socket becomes non-readable, but still writable. You should call the `end()` method explicitly. See ['end'][] event for more information. @@ -86,7 +86,7 @@ specifies: Common options are: - - `allowHalfOpen`: if `true`, the socket won't automatically send + - `allowHalfOpen`: if `true`, the socket won’t automatically send a FIN packet when the other end of the socket sends a FIN packet. Defaults to `false`. See ['end'][] event for more information. @@ -272,7 +272,7 @@ Example: console.log("opened server on %j", address); }); -Don't call `server.address()` until the `'listening'` event has been emitted. +Don’t call `server.address()` until the `'listening'` event has been emitted. ### server.unref() @@ -283,12 +283,12 @@ active server in the event system. If the server is already `unref`d calling ### server.ref() Opposite of `unref`, calling `ref` on a previously `unref`d server will *not* -let the program exit if it's the only server left (the default behavior). If +let the program exit if it’s the only server left (the default behavior). If the server is `ref`d calling `ref` again will have no effect. ### server.maxConnections -Set this property to reject connections when the server's connection count gets +Set this property to reject connections when the server’s connection count gets high. It is not recommended to use this option once a socket has been sent to a child @@ -385,7 +385,7 @@ help users get up and running quickly. The computer cannot always keep up with the amount of data that is written to a socket - the network connection simply might be too slow. Node will internally queue up the data written to a socket and send it out over the wire when it is possible. (Internally it is -polling on the socket's file descriptor for being writable). +polling on the socket’s file descriptor for being writable). The consequence of this internal buffering is that memory may grow. This property shows the number of characters currently buffered to be written. @@ -484,7 +484,7 @@ active socket in the event system. If the socket is already `unref`d calling ### socket.ref() Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not* -let the program exit if it's the only socket left (the default behavior). If +let the program exit if it’s the only socket left (the default behavior). If the socket is `ref`d calling `ref` again will have no effect. ### socket.remoteAddress diff --git a/doc/api/os.markdown b/doc/api/os.markdown index 58a80d074d0042..33d21955c4fadd 100644 --- a/doc/api/os.markdown +++ b/doc/api/os.markdown @@ -8,7 +8,7 @@ Use `require('os')` to access this module. ## os.tmpdir() -Returns the operating system's default directory for temp files. +Returns the operating system’s default directory for temp files. ## os.endianness() diff --git a/doc/api/path.markdown b/doc/api/path.markdown index 0e9a78b15b0d68..69caa82c9fd477 100644 --- a/doc/api/path.markdown +++ b/doc/api/path.markdown @@ -12,7 +12,7 @@ Use `require('path')` to use this module. The following methods are provided: Normalize a string path, taking care of `'..'` and `'.'` parts. -When multiple slashes are found, they're replaced by a single one; +When multiple slashes are found, they’re replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used. @@ -43,7 +43,7 @@ Example: Resolves `to` to an absolute path. -If `to` isn't already absolute `from` arguments are prepended in right to left +If `to` isn’t already absolute `from` arguments are prepended in right to left order, until an absolute path is found. If after using all `from` paths still no absolute path is found, the current working directory is used as well. The resulting path is normalized, and trailing slashes are removed unless the path @@ -61,7 +61,7 @@ Is similar to: cd a/../subfile pwd -The difference is that the different paths don't need to exist and may also be +The difference is that the different paths don’t need to exist and may also be files. Examples: diff --git a/doc/api/process.markdown b/doc/api/process.markdown index 614f5cf07aa225..0e2f30c437c890 100644 --- a/doc/api/process.markdown +++ b/doc/api/process.markdown @@ -16,11 +16,11 @@ cases: handler. * `2` - Unused (reserved by Bash for builtin misuse) * `3` **Internal JavaScript Parse Error** - The JavaScript source code - internal in Node's bootstrapping process caused a parse error. This + internal in Node’s bootstrapping process caused a parse error. This is extremely rare, and generally can only happen during development of Node itself. * `4` **Internal JavaScript Evaluation Failure** - The JavaScript - source code internal in Node's bootstrapping process failed to + source code internal in Node’s bootstrapping process failed to return a function value when evaluated. This is extremely rare, and generally can only happen during development of Node itself. * `5` **Fatal Error** - There was a fatal unrecoverable error in V8. @@ -39,7 +39,7 @@ cases: * `9` - **Invalid Argument** - Either an unknown option was specified, or an option requiring a value was provided without a value. * `10` **Internal JavaScript Run-Time Failure** - The JavaScript - source code internal in Node's bootstrapping process threw an error + source code internal in Node’s bootstrapping process threw an error when the bootstrapping function was called. This is extremely rare, and generally can only happen during development of Node itself. * `12` **Invalid Debug Argument** - The `--debug` and/or `--debug-brk` @@ -56,7 +56,7 @@ Emitted when the process is about to exit. There is no way to prevent the exiting of the event loop at this point, and once all `exit` listeners have finished running the process will exit. Therefore you **must** only perform **synchronous** operations in this handler. This is a good hook to perform -checks on the module's state (like for unit tests). The callback takes one +checks on the module’s state (like for unit tests). The callback takes one argument, the code the process is exiting with. Example of listening for `exit`: @@ -72,7 +72,7 @@ Example of listening for `exit`: ## Event: 'beforeExit' -This event is emitted when node empties it's event loop and has nothing else to +This event is emitted when node empties it’s event loop and has nothing else to schedule. Normally, node exits when there is no work scheduled, but a listener for 'beforeExit' can make asynchronous calls, and cause node to continue. @@ -97,14 +97,14 @@ Example of listening for `uncaughtException`: console.log('This will still run.'); }, 500); - // Intentionally cause an exception, but don't catch it. + // Intentionally cause an exception, but don’t catch it. nonexistentFunc(); console.log('This will not run.'); Note that `uncaughtException` is a very crude mechanism for exception handling. -Don't use it, use [domains](domain.html) instead. If you do use it, restart +Don’t use it, use [domains](domain.html) instead. If you do use it, restart your application after every unhandled exception! Do *not* use it as the node.js equivalent of `On Error Resume Next`. An @@ -126,7 +126,7 @@ standard POSIX signal names such as SIGINT, SIGHUP, etc. Example of listening for `SIGINT`: - // Start reading from stdin so we don't exit. + // Start reading from stdin so we don’t exit. process.stdin.resume(); process.on('SIGINT', function() { @@ -138,8 +138,8 @@ programs. Note: -- `SIGUSR1` is reserved by node.js to start the debugger. It's possible to - install a listener but that won't stop the debugger from starting. +- `SIGUSR1` is reserved by node.js to start the debugger. It’s possible to + install a listener but that won’t stop the debugger from starting. - `SIGTERM` and `SIGINT` have default handlers on non-Windows platforms that resets the terminal mode before exiting with code `128 + signal number`. If one of these signals has a listener installed, its default behaviour will be removed @@ -585,7 +585,7 @@ Getter/setter to set what is displayed in 'ps'. When used as a setter, the maximum length is platform-specific and probably short. -On Linux and OS X, it's limited to the size of the binary name plus the +On Linux and OS X, it’s limited to the size of the binary name plus the length of the command line arguments because it overwrites the argv memory. v0.8 allowed for longer process title strings by also overwriting the environ @@ -595,14 +595,14 @@ cases. ## process.arch -What processor architecture you're running on: `'arm'`, `'ia32'`, or `'x64'`. +What processor architecture you’re running on: `'arm'`, `'ia32'`, or `'x64'`. console.log('This processor architecture is ' + process.arch); ## process.platform -What platform you're running on: +What platform you’re running on: `'darwin'`, `'freebsd'`, `'linux'`, `'sunos'` or `'win32'` console.log('This platform is ' + process.platform); @@ -623,7 +623,7 @@ This will generate: heapTotal: 1826816, heapUsed: 650472 } -`heapTotal` and `heapUsed` refer to V8's memory usage. +`heapTotal` and `heapUsed` refer to V8’s memory usage. ## process.nextTick(callback) @@ -633,7 +633,7 @@ This will generate: Once the current event loop turn runs to completion, call the callback function. -This is *not* a simple alias to `setTimeout(fn, 0)`, it's much more +This is *not* a simple alias to `setTimeout(fn, 0)`, it’s much more efficient. It runs before any additional I/O events (including timers) fire in subsequent ticks of the event loop. @@ -684,7 +684,7 @@ This API is hazardous. If you do this: }); bar(); -then it's not clear whether `foo()` or `bar()` will be called first. +then it’s not clear whether `foo()` or `bar()` will be called first. This approach is much better: @@ -704,7 +704,7 @@ happening, just like a `while(true);` loop. ## process.umask([mask]) -Sets or reads the process's file mode creation mask. Child processes inherit +Sets or reads the process’s file mode creation mask. Child processes inherit the mask from the parent process. Returns the old mask if `mask` argument is given, otherwise returns the current mask. @@ -748,7 +748,7 @@ Alternate way to retrieve [`require.main`](modules.html#modules_accessing_the_main_module). The difference is that if the main module changes at runtime, `require.main` might still refer to the original main module in modules that were required -before the change occurred. Generally it's safe to assume that the two refer +before the change occurred. Generally it’s safe to assume that the two refer to the same module. As with `require.main`, it will be `undefined` if there was no entry script. diff --git a/doc/api/punycode.markdown b/doc/api/punycode.markdown index 2de93213be713a..e3582f97144027 100644 --- a/doc/api/punycode.markdown +++ b/doc/api/punycode.markdown @@ -25,7 +25,7 @@ Converts a string of Unicode symbols to a Punycode string of ASCII-only symbols. ## punycode.toUnicode(domain) Converts a Punycode string representing a domain name to Unicode. Only the -Punycoded parts of the domain name will be converted, i.e. it doesn't matter if +Punycoded parts of the domain name will be converted, i.e. it doesn’t matter if you call it on a string that has already been converted to Unicode. // decode domain names @@ -35,8 +35,8 @@ you call it on a string that has already been converted to Unicode. ## punycode.toASCII(domain) Converts a Unicode string representing a domain name to Punycode. Only the -non-ASCII parts of the domain name will be converted, i.e. it doesn't matter if -you call it with a domain that's already in ASCII. +non-ASCII parts of the domain name will be converted, i.e. it doesn’t matter if +you call it with a domain that’s already in ASCII. // encode domain names punycode.toASCII('mañana.com'); // 'xn--maana-pta.com' diff --git a/doc/api/querystring.markdown b/doc/api/querystring.markdown index e907c4e7d5aa77..4e41cf7021d04a 100644 --- a/doc/api/querystring.markdown +++ b/doc/api/querystring.markdown @@ -39,7 +39,7 @@ Deserialize a query string to an object. Optionally override the default separator (`'&'`) and assignment (`'='`) characters. -Options object may contain `maxKeys` property (equal to 1000 by default), it'll +Options object may contain `maxKeys` property (equal to 1000 by default), it’ll be used to limit processed keys. Set it to 0 to remove key count limitation. Options object may contain `decodeURIComponent` property (`decodeURIComponent` by default), diff --git a/doc/api/readline.markdown b/doc/api/readline.markdown index 055bc39bdf94dd..c53a66d182a3a8 100644 --- a/doc/api/readline.markdown +++ b/doc/api/readline.markdown @@ -5,8 +5,8 @@ To use this module, do `require('readline')`. Readline allows reading of a stream (such as `process.stdin`) on a line-by-line basis. -Note that once you've invoked this module, your node program will not -terminate until you've closed the interface. Here's how to allow your +Note that once you’ve invoked this module, your node program will not +terminate until you’ve closed the interface. Here’s how to allow your program to gracefully exit: var readline = require('readline'); @@ -89,7 +89,7 @@ stream. ### rl.setPrompt(prompt) Sets the prompt, for example when you run `node` on the command line, you see -`> `, which is node's prompt. +`> `, which is node’s prompt. ### rl.prompt([preserveCursor]) @@ -105,9 +105,9 @@ prompt is not written. ### rl.question(query, callback) -Prepends the prompt with `query` and invokes `callback` with the user's +Prepends the prompt with `query` and invokes `callback` with the user’s response. Displays the query to the user, and then invokes `callback` -with the user's response after it has been typed. +with the user’s response after it has been typed. This will also resume the `input` stream used with `createInterface` if it has been paused. @@ -125,7 +125,7 @@ Example usage: Pauses the readline `input` stream, allowing it to be resumed later if needed. -Note that this doesn't immediately pause the stream of events. Several events may be emitted after calling `pause`, including `line`. +Note that this doesn’t immediately pause the stream of events. Several events may be emitted after calling `pause`, including `line`. ### rl.resume() @@ -266,7 +266,7 @@ Example of listening for `SIGCONT`: ## Example: Tiny CLI -Here's an example of how to use all these together to craft a tiny command +Here’s an example of how to use all these together to craft a tiny command line interface: var readline = require('readline'), @@ -296,7 +296,7 @@ Move cursor to the specified position in a given TTY stream. ## readline.moveCursor(stream, dx, dy) -Move cursor relative to it's current position in a given TTY stream. +Move cursor relative to it’s current position in a given TTY stream. ## readline.clearLine(stream, dir) diff --git a/doc/api/repl.markdown b/doc/api/repl.markdown index e5081c3c8db4eb..6aea9c9172e887 100644 --- a/doc/api/repl.markdown +++ b/doc/api/repl.markdown @@ -52,13 +52,13 @@ the following values: - `useColors` - a boolean which specifies whether or not the `writer` function should output colors. If a different `writer` function is set then this does - nothing. Defaults to the repl's `terminal` value. + nothing. Defaults to the repl’s `terminal` value. - `useGlobal` - if set to `true`, then the repl will use the `global` object, instead of running scripts in a separate context. Defaults to `false`. - `ignoreUndefined` - if set to `true`, then the repl will not output the - return value of command if it's `undefined`. Defaults to `false`. + return value of command if it’s `undefined`. Defaults to `false`. - `writer` - the function to invoke for each command that gets evaluated which returns the formatting (including coloring) to display. Defaults to @@ -142,7 +142,7 @@ Example of listening for `exit`: `function (context) {}` -Emitted when the REPL's context is reset. This happens when you type `.clear`. +Emitted when the REPL’s context is reset. This happens when you type `.clear`. If you start the repl with `{ useGlobal: true }` then this event will never be emitted. @@ -194,7 +194,7 @@ Things in the `context` object appear as local within the REPL: There are a few special REPL commands: - `.break` - While inputting a multi-line expression, sometimes you get lost - or just don't care about completing it. `.break` will start over. + or just don’t care about completing it. `.break` will start over. - `.clear` - Resets the `context` object to an empty object and clears any multi-line expression. - `.exit` - Close the I/O stream, which will cause the REPL to exit. diff --git a/doc/api/smalloc.markdown b/doc/api/smalloc.markdown index ff905714e5ed21..f50f4688231b61 100644 --- a/doc/api/smalloc.markdown +++ b/doc/api/smalloc.markdown @@ -38,7 +38,7 @@ this it is possible to allocate external array data to more than a plain Object. v8 does not support allocating external array data to an Array, and if passed will throw. -It's possible is to specify the type of external array data you would like. All +It’s possible is to specify the type of external array data you would like. All possible options are listed in `smalloc.Types`. Example usage: var doubleArr = smalloc.alloc(3, smalloc.Types.Double); diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown index 5ffcef91456a59..9aaa1e48721112 100644 --- a/doc/api/stream.markdown +++ b/doc/api/stream.markdown @@ -59,7 +59,7 @@ var server = http.createServer(function (req, res) { var body = ''; // we want to get the data as utf8 strings - // If you don't set an encoding, then you'll get Buffer objects + // If you don’t set an encoding, then you’ll get Buffer objects req.setEncoding('utf8'); // Readable streams emit 'data' events once a listener is added @@ -152,7 +152,7 @@ When a chunk of data can be read from the stream, it will emit a In some cases, listening for a `'readable'` event will cause some data to be read into the internal buffer from the underlying system, if it -hadn't already. +hadn’t already. ```javascript var readable = getReadableStreamSomehow(); @@ -541,7 +541,7 @@ function writeOneMillionTimes(writer, data, encoding, callback) { writer.write(data, encoding, callback); } else { // see if we should continue, or wait - // don't pass the callback, because we're not done yet. + // don’t pass the callback, because we’re not done yet. ok = writer.write(data, encoding); } } while (i > 0 && ok); @@ -847,7 +847,7 @@ SimpleProtocol.prototype._read = function(n) { if (!this._inBody) { var chunk = this._source.read(); - // if the source doesn't have data, we don't have data yet. + // if the source doesn’t have data, we don’t have data yet. if (chunk === null) return this.push(''); @@ -990,7 +990,7 @@ function SourceWrapper(options) { this._source = getLowlevelSourceObject(); var self = this; - // Every time there's data, we push it into the internal buffer. + // Every time there’s data, we push it into the internal buffer. this._source.ondata = function(chunk) { // if push() returns false, then we need to stop reading from source if (!self.push(chunk)) @@ -1099,7 +1099,7 @@ with an underlying implementation of the `_read(size)` and [`_write(chunk, encoding, callback)`][] methods as you would with a Readable or Writable stream class. -Since JavaScript doesn't have multiple prototypal inheritance, this +Since JavaScript doesn’t have multiple prototypal inheritance, this class prototypally inherits from Readable, and then parasitically from Writable. It is thus up to the user to implement both the lowlevel `_read(n)` method as well as the lowlevel @@ -1344,7 +1344,7 @@ stream is not currently reading, then calling `read(0)` will trigger a low-level `_read` call. There is almost never a need to do this. However, you will see some -cases in Node's internals where this is done, particularly in the +cases in Node’s internals where this is done, particularly in the Readable stream class internals. ### `stream.push('')` @@ -1352,7 +1352,7 @@ Readable stream class internals. Pushing a zero-byte string or Buffer (when not in [Object mode][]) has an interesting side effect. Because it *is* a call to [`stream.push()`][], it will end the `reading` process. However, it -does *not* add any data to the readable buffer, so there's nothing for +does *not* add any data to the readable buffer, so there’s nothing for a user to consume. Very rarely, there are cases where you have no data to provide now, diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown index 92af0b64b4e07b..7c2b3cc75b01c6 100644 --- a/doc/api/timers.markdown +++ b/doc/api/timers.markdown @@ -34,7 +34,7 @@ Stops a interval from triggering. The opaque value returned by `setTimeout` and `setInterval` also has the method `timer.unref()` which will allow you to create a timer that is active but if -it is the only item left in the event loop won't keep the program running. +it is the only item left in the event loop then it won’t keep the program running. If the timer is already `unref`d calling `unref` again will have no effect. In the case of `setTimeout` when you `unref` you create a separate timer that @@ -56,7 +56,7 @@ can also pass arguments to the callback. Callbacks for immediates are queued in the order in which they were created. The entire callback queue is processed every event loop iteration. If you queue -an immediate from a inside an executing callback that immediate won't fire +an immediate from inside an executing callback that immediate won’t fire until the next event loop iteration. ## clearImmediate(immediateObject) diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown index 17172239c540dc..3215308231d46d 100644 --- a/doc/api/tls.markdown +++ b/doc/api/tls.markdown @@ -57,10 +57,10 @@ exceeded. The limits are configurable: - `tls.CLIENT_RENEG_WINDOW`: renegotiation window in seconds, default is 10 minutes. -Don't change the defaults unless you know what you are doing. +Don’t change the defaults unless you know what you are doing. To test your server, connect to it with `openssl s_client -connect address:port` -and tap `R` (that's the letter `R` followed by a carriage return) a few +and tap `R` (that’s the letter `R` followed by a carriage return) a few times. @@ -177,7 +177,7 @@ automatically set as a listener for the [secureConnection][] event. The A `'clientError'` is emitted on the `tls.Server` object whenever a handshake times out. - - `honorCipherOrder` : When choosing a cipher, use the server's preferences + - `honorCipherOrder` : When choosing a cipher, use the server’s preferences instead of the client preferences. Although, this option is disabled by default, it is *recommended* that you @@ -197,7 +197,7 @@ automatically set as a listener for the [secureConnection][] event. The has an effect if `requestCert` is `true`. Default: `false`. - `checkServerIdentity(servername, cert)`: Provide an override for checking - server's hostname against the certificate. Should return an error if verification + server’s hostname against the certificate. Should return an error if verification fails. Return `undefined` if passing. - `NPNProtocols`: An array or `Buffer` of possible NPN protocols. (Protocols @@ -208,7 +208,7 @@ automatically set as a listener for the [secureConnection][] event. The and `cb`. `SNICallback` should invoke `cb(null, ctx)`, where `ctx` is a SecureContext instance. (You can use `tls.createSecureContext(...)` to get proper - SecureContext). If `SNICallback` wasn't provided - default callback with + SecureContext). If `SNICallback` wasn’t provided - default callback with high-level API will be used (see below). - `sessionTimeout`: An integer specifying the seconds after which TLS @@ -324,7 +324,7 @@ Creates a new client connection to the given `port` and `host` (old API) or - `NPNProtocols`: An array of strings or `Buffer`s containing supported NPN protocols. `Buffer`s should have following format: `0x05hello0x05world`, - where first byte is next protocol name's length. (Passing array should + where first byte is next protocol name’s length. (Passing array should usually be much simpler: `['hello', 'world']`.) - `servername`: Servername for SNI (Server Name Indication) TLS extension. @@ -444,7 +444,7 @@ dictionary with keys: Consult for details on the format. -* `honorCipherOrder` : When choosing a cipher, use the server's preferences +* `honorCipherOrder` : When choosing a cipher, use the server’s preferences instead of the client preferences. For further details see `tls` module documentation. @@ -545,7 +545,7 @@ established after addition of event listener. Emitted when client wants to resume previous TLS session. Event listener may perform lookup in external storage using given `sessionId`, and invoke -`callback(null, sessionData)` once finished. If session can't be resumed +`callback(null, sessionData)` once finished. If session can’t be resumed (i.e. doesn't exist in storage) one may call `callback(null, null)`. Calling `callback(err)` will terminate incoming connection and destroy socket. @@ -558,7 +558,7 @@ established after addition of event listener. `function (certificate, issuer, callback) { }` Emitted when the client sends a certificate status request. You could parse -server's current certificate to obtain OCSP url and certificate id, and after +server’s current certificate to obtain OCSP url and certificate id, and after obtaining OCSP response invoke `callback(null, resp)`, where `resp` is a `Buffer` instance. Both `certificate` and `issuer` are a `Buffer` DER-representations of the primary and issuer's certificates. They could be used @@ -618,14 +618,14 @@ more information. ### server.addContext(hostname, context) -Add secure context that will be used if client request's SNI hostname is +Add secure context that will be used if client request’s SNI hostname is matching passed `hostname` (wildcards can be used). `context` can contain `key`, `cert`, `ca` and/or any other properties from `tls.createSecureContext` `options` argument. ### server.maxConnections -Set this property to reject connections when the server's connection count +Set this property to reject connections when the server’s connection count gets high. ### server.connections @@ -655,7 +655,7 @@ common stream methods and events. ### Event: 'secureConnect' This event is emitted after a new connection has been successfully handshaked. -The listener will be called no matter if the server's certificate was +The listener will be called no matter if the server’s certificate was authorized or not. It is up to the user to test `tlsSocket.authorized` to see if the server certificate was signed by one of the specified CAs. If `tlsSocket.authorized === false` then the error can be found in @@ -667,10 +667,10 @@ If `tlsSocket.authorized === false` then the error can be found in `function (response) { }` This event will be emitted if `requestOCSP` option was set. `response` is a -buffer object, containing server's OCSP response. +buffer object, containing server’s OCSP response. -Traditionally, the `response` is a signed object from the server's CA that -contains information about server's certificate revocation status. +Traditionally, the `response` is a signed object from the server’s CA that +contains information about server’s certificate revocation status. ### tlsSocket.encrypted @@ -684,12 +684,12 @@ specified CAs, otherwise `false` ### tlsSocket.authorizationError -The reason why the peer's certificate has not been verified. This property +The reason why the peer’s certificate has not been verified. This property becomes available only when `tlsSocket.authorized === false`. ### tlsSocket.getPeerCertificate([ detailed ]) -Returns an object representing the peer's certificate. The returned object has +Returns an object representing the peer’s certificate. The returned object has some properties corresponding to the field of the certificate. If `detailed` argument is `true` - the full chain with `issuer` property will be returned, if `false` - only the top certificate without `issuer` property. @@ -739,7 +739,7 @@ fields: `rejectUnauthorized`, `requestCert` (See [tls.createServer][] for details). `callback(err)` will be executed with `null` as `err`, once the renegotiation is successfully completed. -NOTE: Can be used to request peer's certificate after the secure connection +NOTE: Can be used to request peer’s certificate after the secure connection has been established. ANOTHER NOTE: When running as the server, socket will be destroyed diff --git a/doc/api/tracing.markdown b/doc/api/tracing.markdown index 92e6809a04a0d4..5cfa665cbf856a 100644 --- a/doc/api/tracing.markdown +++ b/doc/api/tracing.markdown @@ -95,7 +95,7 @@ Explanation of function parameters: * `create(userData)`: A `Function` called when an asynchronous event is instantiated. If a `Value` is returned then it will be attached to the event and overwrite any value that had been passed to -`tracing.createAsyncListener()`'s `userData` argument. If an initial +`tracing.createAsyncListener()`’s `userData` argument. If an initial `userData` was passed when created, then `create()` will receive that as a function argument. @@ -106,10 +106,10 @@ either returned from `create()` or passed during construction (if either occurred). * `after(context, userData)`: A `Function` called immediately after -the asynchronous event's callback has run. Note this will not be called +the asynchronous event’s callback has run. Note this will not be called if the callback throws and the error is not handled. -* `error(userData, error)`: A `Function` called if the event's +* `error(userData, error)`: A `Function` called if the event’s callback threw. If this registered callback returns `true` then Node will assume the error has been properly handled and resume execution normally. When multiple `error()` callbacks have been registered only **one** of @@ -158,7 +158,7 @@ Example usage for capturing errors: return { uid: cntr++ }; }, before: function onBefore(context, storage) { - // Write directly to stdout or we'll enter a recursive loop + // Write directly to stdout or we’ll enter a recursive loop fs.writeSync(1, 'uid: ' + storage.uid + ' is about to run\n'); }, after: function onAfter(context, storage) { @@ -182,7 +182,7 @@ Example usage for capturing errors: // Output: // uid: 0 is about to run // handled error just threw: - // Error: really, it's ok + // Error: really, it’s ok // at /tmp/test2.js:27:9 // at process._tickCallback (node.js:583:11) // at Function.Module.runMain (module.js:492:11) @@ -194,7 +194,7 @@ Example usage for capturing errors: Removes the `AsyncListener` from the listening queue. Removing the `AsyncListener` from the active queue does _not_ mean the -`asyncListener` callbacks will cease to fire on the events they've been +`asyncListener` callbacks will cease to fire on the events they’ve been registered. Subsequently, any asynchronous events fired during the execution of a callback will also have the same `asyncListener` callbacks attached for future execution. For example: @@ -203,7 +203,7 @@ attached for future execution. For example: var key = tracing.createAsyncListener({ create: function asyncListener() { - // Write directly to stdout or we'll enter a recursive loop + // Write directly to stdout or we’ll enter a recursive loop fs.writeSync(1, 'You summoned me?\n'); } }); @@ -219,7 +219,7 @@ attached for future execution. For example: }); }); - // Removing the listener doesn't mean to stop capturing events that + // Removing the listener doesn’t mean to stop capturing events that // have already been added. tracing.removeAsyncListener(key); }, 100); @@ -231,7 +231,7 @@ attached for future execution. For example: // You summoned me? The fact that we logged 4 asynchronous events is an implementation detail -of Node's [Timers][]. +of Node’s [Timers][]. To stop capturing from a specific asynchronous event stack `tracing.removeAsyncListener()` must be called from within the call @@ -241,7 +241,7 @@ stack itself. For example: var key = tracing.createAsyncListener({ create: function asyncListener() { - // Write directly to stdout or we'll enter a recursive loop + // Write directly to stdout or we’ll enter a recursive loop fs.writeSync(1, 'You summoned me?\n'); } }); diff --git a/doc/api/util.markdown b/doc/api/util.markdown index cc639ddb49434b..dd52b8064b2846 100644 --- a/doc/api/util.markdown +++ b/doc/api/util.markdown @@ -5,12 +5,12 @@ These functions are in the module `'util'`. Use `require('util')` to access them. -The `util` module is primarily designed to support the needs of Node's +The `util` module is primarily designed to support the needs of Node’s internal APIs. Many of these utilities are useful for your own programs. If you find that these functions are lacking for your purposes, however, you are encouraged to write your own utilities. We are not interested in any future additions to the `util` module that -are unnecessary for Node's internal functionality. +are unnecessary for Node’s internal functionality. ## util.debuglog(section) @@ -88,7 +88,7 @@ Return a string representation of `object`, which is useful for debugging. An optional *options* object may be passed that alters certain aspects of the formatted string: - - `showHidden` - if `true` then the object's non-enumerable properties will be + - `showHidden` - if `true` then the object’s non-enumerable properties will be shown too. Defaults to `false`. - `depth` - tells `inspect` how many times to recurse while formatting the @@ -99,7 +99,7 @@ formatted string: Defaults to `false`. Colors are customizable, see below. - `customInspect` - if `false`, then custom `inspect(depth, opts)` functions - defined on the objects being inspected won't be called. Defaults to `true`. + defined on the objects being inspected won’t be called. Defaults to `true`. Example of inspecting all properties of the `util` object: diff --git a/doc/api/vm.markdown b/doc/api/vm.markdown index b1453249ec0327..c119734622ee93 100644 --- a/doc/api/vm.markdown +++ b/doc/api/vm.markdown @@ -64,7 +64,7 @@ you can use. This function is useful for creating a sandbox that can be used to run multiple scripts, e.g. if you were emulating a web browser it could be used to create a -single sandbox representing a window's global object, then run all `