diff --git a/Makefile b/Makefile
index e0e87e534b..42679e0b48 100644
--- a/Makefile
+++ b/Makefile
@@ -78,12 +78,15 @@ test-npm-publish: all
out/Release/node: all
apidoc_sources = $(wildcard doc/api/*.markdown)
-apidocs = $(addprefix out/,$(apidoc_sources:.markdown=.html))
+apidocs = $(addprefix out/,$(apidoc_sources:.markdown=.html)) \
+ $(addprefix out/,$(apidoc_sources:.markdown=.json))
-apidoc_dirs = out/doc out/doc/api/ out/doc/api/assets out/doc/about out/doc/community out/doc/logos
+apidoc_dirs = out/doc out/doc/api/ out/doc/api/assets out/doc/about out/doc/community out/doc/logos out/doc/images
apiassets = $(subst api_assets,api/assets,$(addprefix out/,$(wildcard doc/api_assets/*)))
+doc_images = $(addprefix out/,$(wildcard doc/images/* doc/*.jpg doc/*.png))
+
website_files = \
out/doc/index.html \
out/doc/v0.4_announcement.html \
@@ -92,35 +95,14 @@ website_files = \
out/doc/sh_javascript.min.js \
out/doc/sh_vim-dark.css \
out/doc/sh.css \
- out/doc/logo.png \
out/doc/favicon.ico \
out/doc/pipe.css \
out/doc/about/index.html \
- out/doc/close-downloads.png \
out/doc/community/index.html \
- out/doc/community/not-invented-here.png \
out/doc/logos/index.html \
- out/doc/microsoft-logo.png \
- out/doc/ryan-speaker.jpg \
- out/doc/download-logo.png \
- out/doc/ebay-logo.png \
- out/doc/footer-logo-alt.png \
- out/doc/footer-logo.png \
- out/doc/icons-interior.png \
- out/doc/icons.png \
- out/doc/home-icons.png \
- out/doc/joyent-logo_orange_nodeorg-01.png \
- out/doc/linkedin-logo.png \
- out/doc/logo-light.png \
- out/doc/mac_osx_nodejs_installer_logo.png \
- out/doc/microsoft-logo.png \
- out/doc/platform-icons.png \
- out/doc/sponsored.png \
- out/doc/twitter-bird.png \
- out/doc/community-icons.png \
- out/doc/yahoo-logo.png
-
-doc docs: out/Release/node $(apidoc_dirs) $(website_files) $(apiassets) $(apidocs)
+ $(doc_images)
+
+doc: node $(apidoc_dirs) $(website_files) $(apiassets) $(apidocs) tools/doc/
$(apidoc_dirs):
mkdir -p $@
@@ -129,10 +111,13 @@ out/doc/api/assets/%: doc/api_assets/% out/doc/api/assets/
cp $< $@
out/doc/%: doc/%
- cp $< $@
+ cp -r $< $@
+
+out/doc/api/%.json: doc/api/%.markdown
+ out/Release/node tools/doc/generate.js --format=json $< > $@
-out/doc/api/%.html: doc/api/%.markdown out/Release/node $(apidoc_dirs) $(apiassets) tools/doctool/doctool.js
- out/Release/node tools/doctool/doctool.js doc/template.html $< > $@
+out/doc/api/%.html: doc/api/%.markdown
+ out/Release/node tools/doc/generate.js --format=html --template=doc/template.html $< > $@
out/doc/%:
@@ -197,7 +182,7 @@ $(TARBALL): out/doc
cp doc/node.1 $(TARNAME)/doc/node.1
cp -r out/doc/api $(TARNAME)/doc/api
rm -rf $(TARNAME)/deps/v8/test # too big
- rm -rf $(TARNAME)/doc/logos/*.{png,eps} # too big
+ rm -rf $(TARNAME)/doc/images # too big
tar -cf $(TARNAME).tar $(TARNAME)
rm -rf $(TARNAME)
gzip -f -9 $(TARNAME).tar
diff --git a/doc/about/index.html b/doc/about/index.html
index 04ba00aeb1..192424315b 100644
--- a/doc/about/index.html
+++ b/doc/about/index.html
@@ -21,7 +21,7 @@
@@ -102,7 +102,7 @@ console.log('Server running at http://127.0.0.1:1337/');
But what about multiple-processor concurrency? Aren't
threads necessary to scale programs to multi-core computers?
You can start new processes via child_process.fork()
+ href="http://nodejs.org/docs/latest/api/child_process.html#child_process.fork">child_process.fork()
these other processes will be scheduled in parallel. For load
balancing incoming connections across multiple processes use
the
diff --git a/doc/api/_toc.markdown b/doc/api/_toc.markdown
index e2563419e8..73e6b9bd58 100644
--- a/doc/api/_toc.markdown
+++ b/doc/api/_toc.markdown
@@ -1,5 +1,4 @@
-## Table of Contents
-
+* [About these Docs](documentation.html)
* [Synopsis](synopsis.html)
* [Globals](globals.html)
* [STDIO](stdio.html)
@@ -9,8 +8,8 @@
* [Process](process.html)
* [Utilities](util.html)
* [Events](events.html)
-* [Buffers](buffers.html)
-* [Streams](streams.html)
+* [Buffer](buffer.html)
+* [Stream](stream.html)
* [Crypto](crypto.html)
* [TLS/SSL](tls.html)
* [String Decoder](string_decoder.html)
@@ -26,7 +25,7 @@
* [Readline](readline.html)
* [REPL](repl.html)
* [VM](vm.html)
-* [Child Processes](child_processes.html)
+* [Child Processes](child_process.html)
* [Assertion Testing](assert.html)
* [TTY](tty.html)
* [ZLIB](zlib.html)
@@ -35,4 +34,3 @@
* [Cluster](cluster.html)
* Appendixes
* [Appendix 1: Recommended Third-party Modules](appendix_1.html)
- * [Appendix 2: Deprecated API's](appendix_2.html)
diff --git a/doc/api/addons.markdown b/doc/api/addons.markdown
index 4527b24063..ee9f20142e 100644
--- a/doc/api/addons.markdown
+++ b/doc/api/addons.markdown
@@ -1,4 +1,4 @@
-## Addons
+# Addons
Addons are dynamically linked shared objects. They can provide glue to C and
C++ libraries. The API (at the moment) is rather complex, involving
@@ -24,7 +24,7 @@ compiling your module, you don't need to worry about linking to any of these
libraries.
-### Hello world
+## Hello world
To get started let's make a small Addon which is the C++ equivalent of
the following Javascript code:
@@ -129,7 +129,7 @@ In cases where there is more than one `.cc` file, simply add the file name to th
obj.source = ['addon.cc', 'myexample.cc']
-#### Function arguments
+### Function arguments
The following pattern illustrates how to read arguments from JavaScript
function calls and return a result. This is the main and only needed source
@@ -172,7 +172,7 @@ You can test it with the following JavaScript snippet:
console.log( 'This should be eight:', addon.add(3,5) );
-#### Callbacks
+### Callbacks
You can pass JavaScript functions to a C++ function and execute them from
there. Here's `addon.cc`:
@@ -209,7 +209,7 @@ To test it run the following JavaScript snippet:
});
-#### Object factory
+### Object factory
You can create and return new objects from within a C++ function with this
`addon.cc` pattern, which returns an object with property `msg` that echoes
@@ -245,7 +245,7 @@ To test it in JavaScript:
console.log(obj1.msg+' '+obj2.msg); // 'hello world'
-#### Function factory
+### Function factory
This pattern illustrates how to create and return a JavaScript function that
wraps a C++ function:
@@ -286,7 +286,7 @@ To test:
console.log(fn()); // 'hello world'
-#### Wrapping C++ objects
+### Wrapping C++ objects
Here we will create a wrapper for a C++ object/class `MyObject` that can be
instantiated in JavaScript through the `new` operator. First prepare the main
@@ -381,7 +381,7 @@ Test it with:
console.log( obj.plusOne() ); // 13
-#### Factory of wrapped objects
+### Factory of wrapped objects
This is useful when you want to be able to create native objects without
explicitly instantiating them with the `new` operator in JavaScript, e.g.
@@ -507,7 +507,7 @@ Test it with:
console.log( obj2.plusOne() ); // 23
-#### Passing wrapped objects around
+### 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.
diff --git a/doc/api/all.markdown b/doc/api/all.markdown
index 6920ff01db..7b7f736956 100644
--- a/doc/api/all.markdown
+++ b/doc/api/all.markdown
@@ -1,3 +1,4 @@
+@include documentation
@include synopsis
@include globals
@include stdio
@@ -5,12 +6,10 @@
@include modules
@include addons
@include process
-@include constants
@include util
-@include freelist
@include events
-@include buffers
-@include streams
+@include buffer
+@include stream
@include crypto
@include tls
@include string_decoder
@@ -26,14 +25,11 @@
@include readline
@include repl
@include vm
-@include child_processes
+@include child_process
@include assert
@include tty
@include zlib
@include os
@include debugger
@include cluster
-
-# Appendixes
@include appendix_1
-@include appendix_2
diff --git a/doc/api/appendix_1.markdown b/doc/api/appendix_1.markdown
index 59430c20e2..c309b0ca1f 100644
--- a/doc/api/appendix_1.markdown
+++ b/doc/api/appendix_1.markdown
@@ -1,4 +1,4 @@
-## Appendix 1 - Third Party Modules
+# Appendix 1 - Third Party Modules
There are many third party modules for Node. At the time of writing, August
2010, the master repository of modules is
diff --git a/doc/api/appendix_2.markdown b/doc/api/appendix_2.markdown
deleted file mode 100644
index e69de29bb2..0000000000
diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown
index 2e3c0de3ca..be476ce2fd 100644
--- a/doc/api/assert.markdown
+++ b/doc/api/assert.markdown
@@ -1,41 +1,41 @@
-## Assert
+# Assert
This module is used for writing unit tests for your applications, you can
access it with `require('assert')`.
-### assert.fail(actual, expected, message, operator)
+## assert.fail(actual, expected, message, operator)
Throws an exception that displays the values for `actual` and `expected` separated by the provided operator.
-### assert(value, message), assert.ok(value, [message])
+## assert(value, message), assert.ok(value, [message])
Tests if value is a `true` value, it is equivalent to `assert.equal(true, value, message);`
-### assert.equal(actual, expected, [message])
+## assert.equal(actual, expected, [message])
Tests shallow, coercive equality with the equal comparison operator ( `==` ).
-### assert.notEqual(actual, expected, [message])
+## assert.notEqual(actual, expected, [message])
Tests shallow, coercive non-equality with the not equal comparison operator ( `!=` ).
-### assert.deepEqual(actual, expected, [message])
+## assert.deepEqual(actual, expected, [message])
Tests for deep equality.
-### assert.notDeepEqual(actual, expected, [message])
+## assert.notDeepEqual(actual, expected, [message])
Tests for any deep inequality.
-### assert.strictEqual(actual, expected, [message])
+## assert.strictEqual(actual, expected, [message])
Tests strict equality, as determined by the strict equality operator ( `===` )
-### assert.notStrictEqual(actual, expected, [message])
+## assert.notStrictEqual(actual, expected, [message])
Tests strict non-equality, as determined by the strict not equal operator ( `!==` )
-### assert.throws(block, [error], [message])
+## assert.throws(block, [error], [message])
Expects `block` to throw an error. `error` can be constructor, regexp or
validation function.
@@ -72,11 +72,11 @@ Custom error validation:
"unexpected error"
);
-### assert.doesNotThrow(block, [error], [message])
+## assert.doesNotThrow(block, [error], [message])
Expects `block` not to throw an error, see assert.throws for details.
-### assert.ifError(value)
+## assert.ifError(value)
Tests if value is not a false value, throws if it is a true value. Useful when
testing the first argument, `error` in callbacks.
diff --git a/doc/api/buffers.markdown b/doc/api/buffer.markdown
similarity index 71%
rename from doc/api/buffers.markdown
rename to doc/api/buffer.markdown
index 3bc9559173..018664224d 100644
--- a/doc/api/buffers.markdown
+++ b/doc/api/buffer.markdown
@@ -1,4 +1,6 @@
-## Buffers
+# Buffer
+
+ 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
@@ -9,46 +11,63 @@ Raw data is stored in instances of the `Buffer` class. A `Buffer` is similar
to an array of integers but corresponds to a raw memory allocation outside
the V8 heap. A `Buffer` cannot be resized.
-The `Buffer` object is global.
+The `Buffer` class is a global, making it very rare that one would need
+to ever `require('buffer')`.
-Converting between Buffers and JavaScript string objects requires an explicit encoding
-method. Here are the different string encodings;
+Converting between Buffers and JavaScript string objects requires an explicit
+encoding method. Here are the different string encodings.
-* `'ascii'` - for 7 bit ASCII data only. This encoding method is very fast, and will
-strip the high bit if set.
-Note that this encoding converts a null character (`'\0'` or `'\u0000'`) into
-`0x20` (character code of a space). If you want to convert a null character
-into `0x00`, you should use `'utf8'`.
+* `'ascii'` - for 7 bit ASCII data only. This encoding method is very fast, and
+ will strip the high bit if set.
+ Note that this encoding converts a null character (`'\0'` or `'\u0000'`) into
+ `0x20` (character code of a space). If you want to convert a null character
+ into `0x00`, you should use `'utf8'`.
* `'utf8'` - Multi byte encoded Unicode characters. Many web pages and other document formats use UTF-8.
* `'ucs2'` - 2-bytes, little endian encoded Unicode characters. It can encode
-only BMP(Basic Multilingual Plane, U+0000 - U+FFFF).
+ only BMP(Basic Multilingual Plane, U+0000 - U+FFFF).
* `'base64'` - Base64 string encoding.
* `'binary'` - A way of encoding raw binary data into strings by using only
-the first 8 bits of each character. This encoding method is deprecated and
-should be avoided in favor of `Buffer` objects where possible. This encoding
-will be removed in future versions of Node.
+ the first 8 bits of each character. This encoding method is deprecated and
+ should be avoided in favor of `Buffer` objects where possible. This encoding
+ will be removed in future versions of Node.
* `'hex'` - Encode each byte as two hexidecimal characters.
+## Class: Buffer
+
+The Buffer class is a global type for dealing with binary data directly.
+It can be constructed in a variety of ways.
### new Buffer(size)
+* `size` Number
+
Allocates a new buffer of `size` octets.
### new Buffer(array)
+* `array` Array
+
Allocates a new buffer using an `array` of octets.
### new Buffer(str, [encoding])
+* `str` String - string to encode.
+* `encoding` String - encoding to use, Optional.
+
Allocates a new buffer containing the given `str`.
`encoding` defaults to `'utf8'`.
-### buffer.write(string, [offset], [length], [encoding])
+### buf.write(string, [offset], [length], [encoding])
+
+* `string` String - data to be written to buffer
+* `offset` Number, Optional, Default: 0
+* `length` Number, Optional
+* `encoding` String, Optional, Default: 'utf8'
Writes `string` to the buffer at `offset` using the given encoding.
`offset` defaults to `0`, `encoding` defaults to `'utf8'`. `length` is
@@ -66,7 +85,11 @@ bytes written) is set in `Buffer._charsWritten` and will be overwritten the
next time `buf.write()` is called.
-### buffer.toString(encoding, [start], [end])
+### buf.toString([encoding], [start], [end])
+
+* `encoding` String, Optional, Default: 'utf8'
+* `start` Number, Optional, Default: 0
+* `end` Number, Optional
Decodes and returns a string from buffer data encoded with `encoding`
(defaults to `'utf8'`) beginning at `start` (defaults to `0`) and ending at
@@ -75,7 +98,10 @@ Decodes and returns a string from buffer data encoded with `encoding`
See `buffer.write()` example, above.
-### buffer[index]
+### buf[index]
+
+
+
Get and set the octet at `index`. The values refer to individual bytes,
so the legal range is between `0x00` and `0xFF` hex or `0` and `255`.
@@ -93,11 +119,18 @@ Example: copy an ASCII string into a buffer, one byte at a time:
// node.js
-### Buffer.isBuffer(obj)
+### Class Method: Buffer.isBuffer(obj)
+
+* `obj` Object
+* Return: Boolean
Tests if `obj` is a `Buffer`.
-### Buffer.byteLength(string, [encoding])
+### Class Method: Buffer.byteLength(string, [encoding])
+
+* `string` String
+* `encoding` String, Optional, Default: 'utf8'
+* Return: Number
Gives the actual byte length of a string. `encoding` defaults to `'utf8'`.
This is not the same as `String.prototype.length` since that returns the
@@ -112,8 +145,9 @@ Example:
// ½ + ¼ = ¾: 9 characters, 12 bytes
+### buf.length
-### buffer.length
+* Number
The size of the buffer in bytes. Note that this is not necessarily the size
of the contents. `length` refers to the amount of memory allocated for the
@@ -128,7 +162,12 @@ buffer object. It does not change when the contents of the buffer are changed.
// 1234
// 1234
-### buffer.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])
+### buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])
+
+* `targetBuffer` Buffer object - Buffer to copy into
+* `targetStart` Number, Optional, Default: 0
+* `sourceStart` Number, Optional, Default: 0
+* `sourceEnd` Number, Optional, Default: 0
Does copy between buffers. The source and target regions can be overlapped.
`targetStart` and `sourceStart` default to `0`.
@@ -151,7 +190,10 @@ into `buf2`, starting at the 8th byte in `buf2`.
// !!!!!!!!qrst!!!!!!!!!!!!!
-### buffer.slice([start], [end])
+### buf.slice([start], [end])
+
+* `start` Number, Optional, Default: 0
+* `end` Number, Optional, Default: 0
Returns a new buffer which references the same memory as the old, but offset
and cropped by the `start` (defaults to `0`) and `end` (defaults to
@@ -176,7 +218,11 @@ byte from the original Buffer.
// abc
// !bc
-### buffer.readUInt8(offset, [noAssert])
+### buf.readUInt8(offset, [noAssert])
+
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
+* Return: Number
Reads an unsigned 8 bit integer from the buffer at the specified offset.
@@ -201,8 +247,12 @@ Example:
// 0x23
// 0x42
-### buffer.readUInt16LE(offset, [noAssert])
-### buffer.readUInt16BE(offset, [noAssert])
+### buf.readUInt16LE(offset, [noAssert])
+### buf.readUInt16BE(offset, [noAssert])
+
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
+* Return: Number
Reads an unsigned 16 bit integer from the buffer at the specified offset with
specified endian format.
@@ -233,8 +283,12 @@ Example:
// 0x2342
// 0x4223
-### buffer.readUInt32LE(offset, [noAssert])
-### buffer.readUInt32BE(offset, [noAssert])
+### buf.readUInt32LE(offset, [noAssert])
+### buf.readUInt32BE(offset, [noAssert])
+
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
+* Return: Number
Reads an unsigned 32 bit integer from the buffer at the specified offset with
specified endian format.
@@ -257,7 +311,11 @@ Example:
// 0x03042342
// 0x42230403
-### buffer.readInt8(offset, [noAssert])
+### buf.readInt8(offset, [noAssert])
+
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
+* Return: Number
Reads a signed 8 bit integer from the buffer at the specified offset.
@@ -267,8 +325,12 @@ may be beyond the end of the buffer. Defaults to `false`.
Works as `buffer.readUInt8`, except buffer contents are treated as two's
complement signed values.
-### buffer.readInt16LE(offset, [noAssert])
-### buffer.readInt16BE(offset, [noAssert])
+### buf.readInt16LE(offset, [noAssert])
+### buf.readInt16BE(offset, [noAssert])
+
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
+* Return: Number
Reads a signed 16 bit integer from the buffer at the specified offset with
specified endian format.
@@ -279,8 +341,12 @@ may be beyond the end of the buffer. Defaults to `false`.
Works as `buffer.readUInt16*`, except buffer contents are treated as two's
complement signed values.
-### buffer.readInt32LE(offset, [noAssert])
-### buffer.readInt32BE(offset, [noAssert])
+### buf.readInt32LE(offset, [noAssert])
+### buf.readInt32BE(offset, [noAssert])
+
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
+* Return: Number
Reads a signed 32 bit integer from the buffer at the specified offset with
specified endian format.
@@ -291,8 +357,12 @@ may be beyond the end of the buffer. Defaults to `false`.
Works as `buffer.readUInt32*`, except buffer contents are treated as two's
complement signed values.
-### buffer.readFloatLE(offset, [noAssert])
-### buffer.readFloatBE(offset, [noAssert])
+### buf.readFloatLE(offset, [noAssert])
+### buf.readFloatBE(offset, [noAssert])
+
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
+* Return: Number
Reads a 32 bit float from the buffer at the specified offset with specified
endian format.
@@ -313,8 +383,12 @@ Example:
// 0x01
-### buffer.readDoubleLE(offset, [noAssert])
-### buffer.readDoubleBE(offset, [noAssert])
+### buf.readDoubleLE(offset, [noAssert])
+### buf.readDoubleBE(offset, [noAssert])
+
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
+* Return: Number
Reads a 64 bit double from the buffer at the specified offset with specified
endian format.
@@ -339,7 +413,11 @@ Example:
// 0.3333333333333333
-### buffer.writeUInt8(value, offset, [noAssert])
+### buf.writeUInt8(value, offset, [noAssert])
+
+* `value` Number
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset. Note, `value` must be a
valid unsigned 8 bit integer.
@@ -361,8 +439,12 @@ Example:
//
-### buffer.writeUInt16LE(value, offset, [noAssert])
-### buffer.writeUInt16BE(value, offset, [noAssert])
+### buf.writeUInt16LE(value, offset, [noAssert])
+### buf.writeUInt16BE(value, offset, [noAssert])
+
+* `value` Number
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid unsigned 16 bit integer.
@@ -388,8 +470,12 @@ Example:
//
//
-### buffer.writeUInt32LE(value, offset, [noAssert])
-### buffer.writeUInt32BE(value, offset, [noAssert])
+### buf.writeUInt32LE(value, offset, [noAssert])
+### buf.writeUInt32BE(value, offset, [noAssert])
+
+* `value` Number
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid unsigned 32 bit integer.
@@ -413,7 +499,11 @@ Example:
//
//
-### buffer.writeInt8(value, offset, [noAssert])
+### buf.writeInt8(value, offset, [noAssert])
+
+* `value` Number
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset. Note, `value` must be a
valid signed 8 bit integer.
@@ -426,8 +516,12 @@ 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
signed integer into `buffer`.
-### buffer.writeInt16LE(value, offset, [noAssert])
-### buffer.writeInt16BE(value, offset, [noAssert])
+### buf.writeInt16LE(value, offset, [noAssert])
+### buf.writeInt16BE(value, offset, [noAssert])
+
+* `value` Number
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid signed 16 bit integer.
@@ -440,8 +534,12 @@ 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
complement signed integer into `buffer`.
-### buffer.writeInt32LE(value, offset, [noAssert])
-### buffer.writeInt32BE(value, offset, [noAssert])
+### buf.writeInt32LE(value, offset, [noAssert])
+### buf.writeInt32BE(value, offset, [noAssert])
+
+* `value` Number
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid signed 32 bit integer.
@@ -454,8 +552,12 @@ 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
complement signed integer into `buffer`.
-### buffer.writeFloatLE(value, offset, [noAssert])
-### buffer.writeFloatBE(value, offset, [noAssert])
+### buf.writeFloatLE(value, offset, [noAssert])
+### buf.writeFloatBE(value, offset, [noAssert])
+
+* `value` Number
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid 32 bit float.
@@ -479,8 +581,12 @@ Example:
//
//
-### buffer.writeDoubleLE(value, offset, [noAssert])
-### buffer.writeDoubleBE(value, offset, [noAssert])
+### buf.writeDoubleLE(value, offset, [noAssert])
+### buf.writeDoubleBE(value, offset, [noAssert])
+
+* `value` Number
+* `offset` Number
+* `noAssert` Boolean, Optional, Default: false
Writes `value` to the buffer at the specified offset with specified endian
format. Note, `value` must be a valid 64 bit double.
@@ -504,7 +610,11 @@ Example:
//
//
-### buffer.fill(value, [offset], [end])
+### buf.fill(value, [offset], [end])
+
+* `value`
+* `offset` Number, Optional
+* `end` Number, Optional
Fills the buffer with the specified value. If the `offset` (defaults to `0`)
and `end` (defaults to `buffer.length`) are not given it will fill the entire
@@ -513,7 +623,23 @@ buffer.
var b = new Buffer(50);
b.fill("h");
-### INSPECT_MAX_BYTES
+## buffer.INSPECT_MAX_BYTES
+
+* Number, Default: 50
How many bytes will be returned when `buffer.inspect()` is called. This can
be overridden by user modules.
+
+Note that this is a property on the buffer module returned by
+`require('buffer')`, not on the Buffer global, or a buffer instance.
+
+## Class: SlowBuffer
+
+This class is primarily for internal use. JavaScript programs should
+use Buffer instead of using SlowBuffer.
+
+In order to avoid the overhead of allocating many C++ Buffer objects for
+small blocks of memory in the lifetime of a server, Node allocates memory
+in 8Kb (8192 byte) chunks. If a buffer is smaller than this size, then it
+will be backed by a parent SlowBuffer object. If it is larger than this,
+then Node will allocate a SlowBuffer slab for it directly.
diff --git a/doc/api/child_processes.markdown b/doc/api/child_process.markdown
similarity index 65%
rename from doc/api/child_processes.markdown
rename to doc/api/child_process.markdown
index 0d741cadab..3e23dc37ea 100644
--- a/doc/api/child_processes.markdown
+++ b/doc/api/child_process.markdown
@@ -1,21 +1,32 @@
-## Child Processes
+# Child Process
-Node provides a tri-directional `popen(3)` facility through the `ChildProcess`
-class.
+Node provides a tri-directional `popen(3)` facility through the
+`child_process` module.
-It is possible to stream data through the 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.
-To create a child process use `require('child_process').spawn()`.
+To create a child process use `require('child_process').spawn()` or
+`require('child_process').fork()`. The semantics of each are slightly
+different, and explained below.
-Child processes always have three streams associated with them. `child.stdin`,
-`child.stdout`, and `child.stderr`.
+## Class: ChildProcess
`ChildProcess` is an `EventEmitter`.
+Child processes always have three streams associated with them. `child.stdin`,
+`child.stdout`, and `child.stderr`. These may be shared with the stdio
+streams of the parent process, or they may be separate stream objects
+which can be piped to and from.
+
+The ChildProcess class is not intended to be used directly. Use the
+`spawn()` or `fork()` methods to create a Child Process instance.
+
### Event: 'exit'
-`function (code, signal) {}`
+* `code` {Number} the exit code, if it exited normally.
+* `signal` {String} the signal passed to kill the child process, if it
+ was killed by the parent.
This event is emitted after the child process ends. If the process terminated
normally, `code` is the final exit code of the process, otherwise `null`. If
@@ -26,19 +37,36 @@ See `waitpid(2)`.
### child.stdin
+* {Stream object}
+
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
+not be set.
+
### child.stdout
+* {Stream object}
+
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.
+
### child.stderr
+* {Stream object}
+
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.
+
### child.pid
+* {Integer}
+
The PID of the child process.
Example:
@@ -49,8 +77,48 @@ Example:
console.log('Spawned child pid: ' + grep.pid);
grep.stdin.end();
+### child.kill([signal])
+
+* `signal` {String}
+
+Send a signal to the child process. If no argument is given, the process will
+be sent `'SIGTERM'`. See `signal(7)` for a list of available signals.
+
+ var spawn = require('child_process').spawn,
+ grep = spawn('grep', ['ssh']);
+
+ grep.on('exit', function (code, signal) {
+ console.log('child process terminated due to receipt of signal '+signal);
+ });
+
+ // send SIGHUP to process
+ grep.kill('SIGHUP');
+
+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 to a process.
+
+See `kill(2)`
+
+### child.send(message, [sendHandle])
+
+* `message` {Object}
+* `sendHandle` {Handle object}
+
+Send a message (and, optionally, a handle object) to a child process.
+
+See `child_process.fork()` for details.
-### child_process.spawn(command, [args], [options])
+## child_process.spawn(command, [args], [options])
+
+* `command` {String} The command to run
+* `args` {Array} List of string arguments
+* `options` {Object}
+ * `cwd` {String} Current working directory of the child process
+ * `customFds` {Array} **Deprecated** File descriptors for the child to use
+ for stdio. (See below)
+ * `env` {Object} Environment key-value pairs
+ * `setsid` {Boolean}
+* return: {ChildProcess object}
Launches a new process with the given `command`, with command line arguments in `args`.
If omitted, `args` defaults to an empty Array.
@@ -140,17 +208,34 @@ API.
There is a deprecated option called `customFds` which allows one to specify
specific file descriptors for the stdio of the child process. This API was
not portable to all platforms and therefore removed.
-With `customFds` it was possible to hook up the new process' [stdin, stdout,
-stderr] to existing streams; `-1` meant that a new stream should be created.
+With `customFds` it was possible to hook up the new process' `[stdin, stdout,
+stderr]` to existing streams; `-1` meant that a new stream should be created.
Use at your own risk.
There are several internal options. In particular `stdinStream`,
`stdoutStream`, `stderrStream`. They are for INTERNAL USE ONLY. As with all
undocumented APIs in Node, they should not be used.
-See also: `child_process.exec()`
-
-### child_process.exec(command, [options], callback)
+See also: `child_process.exec()` and `child_process.fork()`
+
+## child_process.exec(command, [options], callback)
+
+* `command` {String} The command to run, with space-separated arguments
+* `options` {Object}
+ * `cwd` {String} Current working directory of the child process
+ * `customFds` {Array} **Deprecated** File descriptors for the child to use
+ for stdio. (See below)
+ * `env` {Object} Environment key-value pairs
+ * `setsid` {Boolean}
+ * `encoding` {String} (Default: 'utf8')
+ * `timeout` {Number} (Default: 0)
+ * `maxBuffer` {Number} (Default: 200*1024)
+ * `killSignal` {String} (Default: 'SIGTERM')
+* `callback` {Function} called with the output when process terminates
+ * `code` {Integer} Exit code
+ * `stdout` {Buffer}
+ * `stderr` {Buffer}
+* Return: ChildProcess object
Runs a command in a shell and buffers the output.
@@ -172,7 +257,8 @@ will be `null`. On error, `error` will be an instance of `Error` and `err.code`
will be the exit code of the child process, and `err.signal` will be set to the
signal that terminated the process.
-There is a second optional argument to specify several options. The default options are
+There is a second optional argument to specify several options. The
+default options are
{ encoding: 'utf8',
timeout: 0,
@@ -188,14 +274,48 @@ amount of data allowed on stdout or stderr - if this value is exceeded then
the child process is killed.
-### child_process.execFile(file, args, options, callback)
+## child_process.execFile(file, args, options, callback)
+
+* `file` {String} The filename of the program to run
+* `args` {Array} List of string arguments
+* `options` {Object}
+ * `cwd` {String} Current working directory of the child process
+ * `customFds` {Array} **Deprecated** File descriptors for the child to use
+ for stdio. (See below)
+ * `env` {Object} Environment key-value pairs
+ * `setsid` {Boolean}
+ * `encoding` {String} (Default: 'utf8')
+ * `timeout` {Number} (Default: 0)
+ * `maxBuffer` {Number} (Default: 200*1024)
+ * `killSignal` {String} (Default: 'SIGTERM')
+* `callback` {Function} called with the output when process terminates
+ * `code` {Integer} Exit code
+ * `stdout` {Buffer}
+ * `stderr` {Buffer}
+* Return: ChildProcess object
This is similar to `child_process.exec()` except it does not execute a
subshell but rather the specified file directly. This makes it slightly
leaner than `child_process.exec`. It has the same options.
-### child_process.fork(modulePath, arguments, options)
+## child_process.fork(modulePath, [args], [options])
+
+* `modulePath` {String} The module to run in the child
+* `args` {Array} List of string arguments
+* `options` {Object}
+ * `cwd` {String} Current working directory of the child process
+ * `customFds` {Array} **Deprecated** File descriptors for the child to use
+ for stdio. (See below)
+ * `env` {Object} Environment key-value pairs
+ * `setsid` {Boolean}
+ * `encoding` {String} (Default: 'utf8')
+ * `timeout` {Number} (Default: 0)
+* `callback` {Function} called with the output when process terminates
+ * `code` {Integer} Exit code
+ * `stdout` {Buffer}
+ * `stderr` {Buffer}
+* Return: ChildProcess object
This is a special case of the `spawn()` functionality for spawning Node
processes. In addition to having all the methods in a normal ChildProcess
@@ -256,22 +376,3 @@ processes:
-### child.kill([signal])
-
-Send a signal to the child process. If no argument is given, the process will
-be sent `'SIGTERM'`. See `signal(7)` for a list of available signals.
-
- var spawn = require('child_process').spawn,
- grep = spawn('grep', ['ssh']);
-
- grep.on('exit', function (code, signal) {
- console.log('child process terminated due to receipt of signal '+signal);
- });
-
- // send SIGHUP to process
- grep.kill('SIGHUP');
-
-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 to a process.
-
-See `kill(2)`
diff --git a/doc/api/cluster.markdown b/doc/api/cluster.markdown
index 7f1b19c69f..39e9444d1f 100644
--- a/doc/api/cluster.markdown
+++ b/doc/api/cluster.markdown
@@ -1,4 +1,4 @@
-## Cluster
+# Cluster
A single instance of Node runs in a single thread. To take advantage of
multi-core systems the user will sometimes want to launch a cluster of Node
@@ -72,18 +72,18 @@ in the master process via message passing:
-### cluster.fork()
+## cluster.fork()
Spawn a new worker process. This can only be called from the master process.
-### cluster.isMaster
-### cluster.isWorker
+## cluster.isMaster
+## cluster.isWorker
Boolean flags to determine if the current process is a master or a worker
process in a cluster. A process `isMaster` if `process.env.NODE_WORKER_ID`
is undefined.
-### Event: 'death'
+## Event: 'death'
When any of the workers die the cluster module will emit the 'death' event.
This can be used to restart the worker by calling `fork()` again.
@@ -92,6 +92,6 @@ This can be used to restart the worker by calling `fork()` again.
console.log('worker ' + worker.pid + ' died. restart...');
cluster.fork();
});
-
+
Different techniques can be used to restart the worker depending on the
application.
diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown
index fd516acd6a..1776412512 100644
--- a/doc/api/crypto.markdown
+++ b/doc/api/crypto.markdown
@@ -1,4 +1,4 @@
-## Crypto
+# Crypto
Use `require('crypto')` to access this module.
@@ -8,7 +8,7 @@ of a secure HTTPS net or http connection.
It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods.
-### crypto.createCredentials(details)
+## crypto.createCredentials(details)
Creates a credentials object, with the optional details being a dictionary with keys:
@@ -23,7 +23,7 @@ If no 'ca' details are given, then node.js will use the default publicly trusted
.
-### crypto.createHash(algorithm)
+## crypto.createHash(algorithm)
Creates and returns a hash object, a cryptographic hash with the given algorithm
which can be used to generate hash digests.
@@ -50,6 +50,12 @@ Example: this program that takes the sha1 sum of a file
console.log(d + ' ' + filename);
});
+## Class: Hash
+
+The class for creating hash digests of data.
+
+Returned by `crypto.createHash`.
+
### hash.update(data, [input_encoding])
Updates the hash content with the given `data`, the encoding of which is given
@@ -66,13 +72,19 @@ Defaults to `'binary'`.
Note: `hash` object can not be used after `digest()` method been called.
-### crypto.createHmac(algorithm, key)
+## crypto.createHmac(algorithm, key)
Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key.
`algorithm` is dependent on the available algorithms supported by OpenSSL - see createHash above.
`key` is the hmac key to be used.
+## Class: Hmac
+
+Class for creating cryptographic hmac content.
+
+Returned by `crypto.createHmac`.
+
### hmac.update(data)
Update the hmac content with the given `data`.
@@ -87,7 +99,7 @@ Defaults to `'binary'`.
Note: `hmac` object can not be used after `digest()` method been called.
-### crypto.createCipher(algorithm, password)
+## crypto.createCipher(algorithm, password)
Creates and returns a cipher object, with the given algorithm and password.
@@ -95,15 +107,21 @@ Creates and returns a cipher object, with the given algorithm and password.
On recent releases, `openssl list-cipher-algorithms` will display the
available cipher algorithms.
`password` is used to derive key and IV, which must be `'binary'` encoded
-string (See the [Buffers](buffers.html) for more information).
+string (See the [Buffer section](buffer.html) for more information).
-### crypto.createCipheriv(algorithm, key, iv)
+## crypto.createCipheriv(algorithm, key, iv)
Creates and returns a cipher object, with the given algorithm, key and iv.
`algorithm` is the same as the `createCipher()`. `key` is a raw key used in
algorithm. `iv` is an Initialization vector. `key` and `iv` must be `'binary'`
-encoded string (See the [Buffers](buffers.html) for more information).
+encoded string (See the [Buffer section](buffer.html) for more information).
+
+## Class: Cipher
+
+Class for encrypting data.
+
+Returned by `crypto.createCipher` and `crypto.createCipheriv`.
### cipher.update(data, [input_encoding], [output_encoding])
@@ -124,16 +142,22 @@ Returns any remaining enciphered contents, with `output_encoding` being one of:
Note: `cipher` object can not be used after `final()` method been called.
-### crypto.createDecipher(algorithm, password)
+## crypto.createDecipher(algorithm, password)
Creates and returns a decipher object, with the given algorithm and key.
This is the mirror of the [createCipher()](#crypto.createCipher) above.
-### crypto.createDecipheriv(algorithm, key, iv)
+## crypto.createDecipheriv(algorithm, key, iv)
Creates and returns a decipher object, with the given algorithm, key and iv.
This is the mirror of the [createCipheriv()](#crypto.createCipheriv) above.
+## Class: Decipher
+
+Class for decrypting data.
+
+Returned by `crypto.createDecipher` and `crypto.createDecipheriv`.
+
### decipher.update(data, [input_encoding], [output_encoding])
Updates the decipher with `data`, which is encoded in `'binary'`, `'base64'`
@@ -151,12 +175,18 @@ Defaults to `'binary'`.
Note: `decipher` object can not be used after `final()` method been called.
-### crypto.createSign(algorithm)
+## crypto.createSign(algorithm)
Creates and returns a signing object, with the given algorithm.
On recent OpenSSL releases, `openssl list-public-key-algorithms` will display
the available signing algorithms. Examples are `'RSA-SHA256'`.
+## Class: Signer
+
+Class for generating signatures.
+
+Returned by `crypto.createSign`.
+
### signer.update(data)
Updates the signer object with data.
@@ -172,12 +202,17 @@ Returns the signature in `output_format` which can be `'binary'`, `'hex'` or
Note: `signer` object can not be used after `sign()` method been called.
-
-### crypto.createVerify(algorithm)
+## crypto.createVerify(algorithm)
Creates and returns a verification object, with the given algorithm.
This is the mirror of the signing object above.
+## Class: Verify
+
+Class for verifying signatures.
+
+Returned by `crypto.createVerify`.
+
### verifier.update(data)
Updates the verifier object with data.
@@ -195,17 +230,23 @@ Returns true or false depending on the validity of the signature for the data an
Note: `verifier` object can not be used after `verify()` method been called.
-### crypto.createDiffieHellman(prime_length)
+## crypto.createDiffieHellman(prime_length)
Creates a Diffie-Hellman key exchange object and generates a prime of the
given bit length. The generator used is `2`.
-### crypto.createDiffieHellman(prime, [encoding])
+## crypto.createDiffieHellman(prime, [encoding])
Creates a Diffie-Hellman key exchange object using the supplied prime. The
generator used is `2`. Encoding can be `'binary'`, `'hex'`, or `'base64'`.
Defaults to `'binary'`.
+## Class: DiffieHellman
+
+The class for creating Diffie-Hellman key exchanges.
+
+Returned by `crypto.createDiffieHellman`.
+
### diffieHellman.generateKeys([encoding])
Generates private and public Diffie-Hellman key values, and returns the
@@ -252,13 +293,13 @@ or `'base64'`. Defaults to `'binary'`.
Sets the Diffie-Hellman private key. Key encoding can be `'binary'`, `'hex'`,
or `'base64'`. Defaults to `'binary'`.
-### pbkdf2(password, salt, iterations, keylen, callback)
+## crypto.pbkdf2(password, salt, iterations, keylen, callback)
Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive
a key of given length from the given password, salt and iterations.
The callback gets two arguments `(err, derivedKey)`.
-### randomBytes(size, [callback])
+## crypto.randomBytes(size, [callback])
Generates cryptographically strong pseudo-random data. Usage:
diff --git a/doc/api/debugger.markdown b/doc/api/debugger.markdown
index 5583f8685d..4f4cead808 100644
--- a/doc/api/debugger.markdown
+++ b/doc/api/debugger.markdown
@@ -1,4 +1,6 @@
-## Debugger
+# Debugger
+
+
V8 comes with an extensive debugger which is accessible out-of-process via a
simple [TCP protocol](http://code.google.com/p/v8/wiki/DebuggerProtocol).
@@ -74,7 +76,7 @@ The `repl` command allows you to evaluate code remotely. The `next` command
steps over to the next line. There are a few other commands available and more
to come. Type `help` to see others.
-### Watchers
+## Watchers
You can watch expression and variable values while debugging your code.
On every breakpoint each expression from the watchers list will be evaluated
@@ -85,16 +87,16 @@ To start watching an expression, type `watch("my_expression")`. `watchers`
prints the active watchers. To remove a watcher, type
`unwatch("my_expression")`.
-### Commands reference
+## Commands reference
-#### Stepping
+### Stepping
* `cont`, `c` - Continue execution
* `next`, `n` - Step next
* `step`, `s` - Step in
* `out`, `o` - Step out
-#### Breakpoints
+### Breakpoints
* `setBreakpoint()`, `sb()` - Set breakpoint on current line
* `setBreakpoint('fn()')`, `sb(...)` - Set breakpoint on a first statement in
@@ -103,7 +105,7 @@ functions body
script.js
* `clearBreakpoint`, `cb(...)` - Clear breakpoint
-#### Info
+### Info
* `backtrace`, `bt` - Print backtrace of current execution frame
* `list(5)` - List scripts source code with 5 line context (5 lines before and
@@ -114,21 +116,19 @@ after)
breakpoint)
* `repl` - Open debugger's repl for evaluation in debugging script's context
-#### Execution control
+### Execution control
* `run` - Run script (automatically runs on debugger's start)
* `restart` - Restart script
* `kill` - Kill script
-#### Various
+### Various
* `scripts` - List all loaded scripts
* `version` - Display v8's version
-### Advanced Usage
+## Advanced Usage
The V8 debugger can be enabled and accessed either by starting Node with
the `--debug` command-line flag or by signaling an existing Node process
with `SIGUSR1`.
-
-
diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown
index d057b412fb..150d5d8b15 100644
--- a/doc/api/dgram.markdown
+++ b/doc/api/dgram.markdown
@@ -1,50 +1,65 @@
-## UDP / Datagram Sockets
+# UDP / Datagram Sockets
+
+
Datagram sockets are available through `require('dgram')`.
+## dgram.createSocket(type, [callback])
+
+* `type` String. Either 'udp4' or 'udp6'
+* `callback` Function. Attached as a listener to `message` events.
+ Optional
+* Returns: Socket object
+
+Creates a datagram Socket of the specified types. Valid types are `udp4`
+and `udp6`.
+
+Takes an optional callback which is added as a listener for `message` events.
+
+Call `socket.bind` if you want to receive datagrams. `socket.bind()` will bind
+to the "all interfaces" address on a random port (it does the right thing for
+both `udp4` and `udp6` sockets). You can then retrieve the address and port
+with `socket.address().address` and `socket.address().port`.
+
+## Class: Socket
+
+The dgram Socket class encapsulates the datagram functionality. It
+should be created via `dgram.createSocket(type, [callback])`.
+
### Event: 'message'
-`function (msg, rinfo) { }`
+* `msg` Buffer object. The message
+* `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 and the number of bytes in the datagram.
### Event: 'listening'
-`function () { }`
-
Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets
are created.
### Event: 'close'
-`function () { }`
-
Emitted when a socket is closed with `close()`. No new `message` events will be emitted
on this socket.
### Event: 'error'
-`function (exception) {}`
+* `exception` Error object
Emitted when an error occurs.
----
-
-### dgram.createSocket(type, [callback])
-
-Creates a datagram socket of the specified types. Valid types are `udp4`
-and `udp6`.
-
-Takes an optional callback which is added as a listener for `message` events.
-
-Call `socket.bind` if you want to receive datagrams. `socket.bind()` will bind
-to the "all interfaces" address on a random port (it does the right thing for
-both `udp4` and `udp6` sockets). You can then retrieve the address and port
-with `socket.address().address` and `socket.address().port`.
-
### dgram.send(buf, offset, length, port, address, [callback])
+* `buf` Buffer object. Message to be sent
+* `offset` Integer. Offset in the buffer where the message starts.
+* `length` Integer. Number of bytes in the message.
+* `port` Integer. destination port
+* `address` String. destination IP
+* `callback` Function. Callback when message is done being delivered.
+ Optional.
+
For UDP sockets, the destination port and IP address must be specified. A string
may be supplied for the `address` parameter, and it will be resolved with DNS. An
optional callback may be specified to detect any DNS errors and when `buf` may be
@@ -93,6 +108,9 @@ informing the source that the data did not reach its intended recipient).
### dgram.bind(port, [address])
+* `port` Integer
+* `address` String, Optional
+
For UDP sockets, listen for datagrams on a named `port` and optional `address`. If
`address` is not specified, the OS will try to listen on all addresses.
@@ -128,11 +146,15 @@ this object will contain `address` and `port`.
### dgram.setBroadcast(flag)
+* `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.
### dgram.setTTL(ttl)
+* `ttl` Integer
+
Sets the `IP_TTL` socket option. TTL stands for "Time to Live," but in this context it
specifies the number of IP hops that a packet is allowed to go through. Each router or
gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a
@@ -144,6 +166,8 @@ systems is 64.
### dgram.setMulticastTTL(ttl)
+* `ttl` Integer
+
Sets the `IP_MULTICAST_TTL` socket option. TTL stands for "Time to Live," but in this
context it specifies the number of IP hops that a packet is allowed to go through,
specifically for multicast traffic. Each router or gateway that forwards a packet
@@ -154,11 +178,16 @@ systems is 64.
### dgram.setMulticastLoopback(flag)
+* `flag` Boolean
+
Sets or clears the `IP_MULTICAST_LOOP` socket option. When this option is set, multicast
packets will also be received on the local interface.
### dgram.addMembership(multicastAddress, [multicastInterface])
+* `multicastAddress` String
+* `multicastInterface` String, Optional
+
Tells the kernel to join a multicast group with `IP_ADD_MEMBERSHIP` socket option.
If `multicastInterface` is not specified, the OS will try to add membership to all valid
@@ -166,6 +195,9 @@ interfaces.
### dgram.dropMembership(multicastAddress, [multicastInterface])
+* `multicastAddress` String
+* `multicastInterface` String, Optional
+
Opposite of `addMembership` - tells the kernel to leave a multicast group with
`IP_DROP_MEMBERSHIP` socket option. This is automatically called by the kernel
when the socket is closed or process terminates, so most apps will never need to call
diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown
index 1f54e2dd3c..93d8bca233 100644
--- a/doc/api/dns.markdown
+++ b/doc/api/dns.markdown
@@ -1,4 +1,4 @@
-## DNS
+# DNS
Use `require('dns')` to access this module. All methods in the dns module
use C-Ares except for `dns.lookup` which uses `getaddrinfo(3)` in a thread
@@ -31,7 +31,7 @@ resolves the IP addresses which are returned.
});
});
-### dns.lookup(domain, [family], callback)
+## dns.lookup(domain, [family], callback)
Resolves a domain (e.g. `'google.com'`) into the first found A (IPv4) or
AAAA (IPv6) record.
@@ -44,7 +44,7 @@ is either the integer 4 or 6 and denotes the family of `address` (not
necessarily the value initially passed to `lookup`).
-### dns.resolve(domain, [rrtype], callback)
+## dns.resolve(domain, [rrtype], callback)
Resolves a domain (e.g. `'google.com'`) into an array of the record types
specified by rrtype. Valid rrtypes are `'A'` (IPV4 addresses, default),
@@ -61,50 +61,50 @@ one of the error codes listed below and `err.message` is a string describing
the error in English.
-### dns.resolve4(domain, callback)
+## dns.resolve4(domain, callback)
The same as `dns.resolve()`, but only for IPv4 queries (`A` records).
`addresses` is an array of IPv4 addresses (e.g.
`['74.125.79.104', '74.125.79.105', '74.125.79.106']`).
-### dns.resolve6(domain, callback)
+## dns.resolve6(domain, callback)
The same as `dns.resolve4()` except for IPv6 queries (an `AAAA` query).
-### dns.resolveMx(domain, callback)
+## dns.resolveMx(domain, callback)
The same as `dns.resolve()`, but only for mail exchange queries (`MX` records).
`addresses` is an array of MX records, each with a priority and an exchange
attribute (e.g. `[{'priority': 10, 'exchange': 'mx.example.com'},...]`).
-### dns.resolveTxt(domain, callback)
+## dns.resolveTxt(domain, callback)
The same as `dns.resolve()`, but only for text queries (`TXT` records).
`addresses` is an array of the text records available for `domain` (e.g.,
`['v=spf1 ip4:0.0.0.0 ~all']`).
-### dns.resolveSrv(domain, callback)
+## dns.resolveSrv(domain, callback)
The same as `dns.resolve()`, but only for service records (`SRV` records).
`addresses` is an array of the SRV records available for `domain`. Properties
of SRV records are priority, weight, port, and name (e.g.,
`[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]`).
-### dns.reverse(ip, callback)
+## dns.reverse(ip, callback)
Reverse resolves an ip address to an array of domain names.
The callback has arguments `(err, domains)`.
-### dns.resolveNs(domain, callback)
+## dns.resolveNs(domain, callback)
The same as `dns.resolve()`, but only for name server records (`NS` records).
`addresses` is an array of the name server records available for `domain`
(e.g., `['ns1.example.com', 'ns2.example.com']`).
-### dns.resolveCname(domain, callback)
+## dns.resolveCname(domain, callback)
The same as `dns.resolve()`, but only for canonical name records (`CNAME`
records). `addresses` is an array of the canonical name records available for
diff --git a/doc/api/documentation.markdown b/doc/api/documentation.markdown
new file mode 100644
index 0000000000..d3c7a86928
--- /dev/null
+++ b/doc/api/documentation.markdown
@@ -0,0 +1,59 @@
+# About this Documentation
+
+
+
+The goal of this documentation is to comprehensively explain the Node.js
+API, both from a reference as well as a conceptual point of view. Each
+section describes a built-in module or high-level concept.
+
+Where appropriate, property types, method arguments, and the arguments
+provided to event handlers are detailed in a list underneath the topic
+heading.
+
+Every `.html` document has a corresponding `.json` document presenting
+the same information in a structured manner. This feature is
+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
+documentation is generated using the `tools/doc/generate.js` program.
+The HTML template is located at `doc/template.html`.
+
+## Stability Index
+
+
+
+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
+all. Others are brand new and experimental, or known to be hazardous
+and in the process of being redesigned.
+
+The notices look like this:
+
+ Stability: 1 Experimental
+
+The stability indices are as follows:
+
+* **0 - Deprecated** This feature is known to be problematic, and changes are
+planned. Do not rely on it. Use of the feature may cause warnings. Backwards
+compatibility should not be expected.
+
+* **1 - Experimental** This feature was introduced recently, and may change
+or be removed in future versions. Please try it out and provide feedback.
+If it addresses a use-case that is important to you, tell the node core team.
+
+* **2 - Unstable** The API is in the process of settling, but has not yet had
+sufficient real-world testing to be considered stable. Backwards-compatibility
+will be maintained if reasonable.
+
+* **3 - Stable** The API has proven satisfactory, but cleanup in the underlying
+code may cause minor changes. Backwards-compatibility is guaranteed.
+
+* **4 - API Frozen** This API has been tested extensively in production and is
+unlikely to ever have to change.
+
+* **5 - Locked** Unless serious bugs are found, this code will not ever
+change. Please do not suggest changes in this area; they will be refused.
diff --git a/doc/api/events.markdown b/doc/api/events.markdown
index 660f36e178..b9000f2928 100644
--- a/doc/api/events.markdown
+++ b/doc/api/events.markdown
@@ -1,4 +1,6 @@
-## Events
+# Events
+
+
Many objects in Node emit events: a `net.Server` emits an event each time
a peer connects to it, a `fs.readStream` emits an event when the file is
@@ -12,7 +14,7 @@ Functions can then be attached to objects, to be executed when an event
is emitted. These functions are called _listeners_.
-### events.EventEmitter
+## Class: events.EventEmitter
To access the EventEmitter class, `require('events').EventEmitter`.
@@ -24,8 +26,8 @@ trace and exit the program.
All EventEmitters emit the event `'newListener'` when new listeners are
added.
-#### emitter.addListener(event, listener)
-#### emitter.on(event, listener)
+### emitter.addListener(event, listener)
+### emitter.on(event, listener)
Adds a listener to the end of the listeners array for the specified event.
@@ -33,7 +35,7 @@ Adds a listener to the end of the listeners array for the specified event.
console.log('someone connected!');
});
-#### emitter.once(event, listener)
+### emitter.once(event, listener)
Adds a **one time** listener for the event. This listener is
invoked only the next time the event is fired, after which
@@ -43,7 +45,7 @@ it is removed.
console.log('Ah, we have our first user!');
});
-#### emitter.removeListener(event, listener)
+### emitter.removeListener(event, listener)
Remove a listener from the listener array for the specified event.
**Caution**: changes array indices in the listener array behind the listener.
@@ -56,12 +58,12 @@ Remove a listener from the listener array for the specified event.
server.removeListener('connection', callback);
-#### emitter.removeAllListeners([event])
+### emitter.removeAllListeners([event])
Removes all listeners, or those of the specified event.
-#### emitter.setMaxListeners(n)
+### emitter.setMaxListeners(n)
By default EventEmitters will print a warning if more than 10 listeners are
added for a particular event. This is a useful default which helps finding memory leaks.
@@ -69,7 +71,7 @@ Obviously not all Emitters should be limited to 10. This function allows
that to be increased. Set to zero for unlimited.
-#### emitter.listeners(event)
+### emitter.listeners(event)
Returns an array of listeners for the specified event. This array can be
manipulated, e.g. to remove listeners.
@@ -79,12 +81,13 @@ manipulated, e.g. to remove listeners.
});
console.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
-#### emitter.emit(event, [arg1], [arg2], [...])
+### emitter.emit(event, [arg1], [arg2], [...])
Execute each of the listeners in order with the supplied arguments.
-#### Event: 'newListener'
+### Event: 'newListener'
-`function (event, listener) { }`
+* `event` {String} The event name
+* `listener` {Function} The event handler function
This event is emitted any time someone adds a new listener.
diff --git a/doc/api/fs.markdown b/doc/api/fs.markdown
index 88d4c28294..55ee35a0f5 100644
--- a/doc/api/fs.markdown
+++ b/doc/api/fs.markdown
@@ -1,4 +1,4 @@
-## File System
+# File System
File I/O is provided by simple wrappers around standard POSIX functions. To
use this module do `require('fs')`. All the methods have asynchronous and
@@ -58,195 +58,195 @@ the entire process until they complete--halting all connections.
Relative path to filename can be used, remember however that this path will be relative
to `process.cwd()`.
-### fs.rename(path1, path2, [callback])
+## fs.rename(path1, path2, [callback])
Asynchronous rename(2). No arguments other than a possible exception are given
to the completion callback.
-### fs.renameSync(path1, path2)
+## fs.renameSync(path1, path2)
Synchronous rename(2).
-### fs.truncate(fd, len, [callback])
+## fs.truncate(fd, len, [callback])
Asynchronous ftruncate(2). No arguments other than a possible exception are
given to the completion callback.
-### fs.truncateSync(fd, len)
+## fs.truncateSync(fd, len)
Synchronous ftruncate(2).
-### fs.chown(path, uid, gid, [callback])
+## fs.chown(path, uid, gid, [callback])
Asynchronous chown(2). No arguments other than a possible exception are given
to the completion callback.
-### fs.chownSync(path, uid, gid)
+## fs.chownSync(path, uid, gid)
Synchronous chown(2).
-### fs.fchown(fd, uid, gid, [callback])
+## fs.fchown(fd, uid, gid, [callback])
Asynchronous fchown(2). No arguments other than a possible exception are given
to the completion callback.
-### fs.fchownSync(fd, uid, gid)
+## fs.fchownSync(fd, uid, gid)
Synchronous fchown(2).
-### fs.lchown(path, uid, gid, [callback])
+## fs.lchown(path, uid, gid, [callback])
Asynchronous lchown(2). No arguments other than a possible exception are given
to the completion callback.
-### fs.lchownSync(path, uid, gid)
+## fs.lchownSync(path, uid, gid)
Synchronous lchown(2).
-### fs.chmod(path, mode, [callback])
+## fs.chmod(path, mode, [callback])
Asynchronous chmod(2). No arguments other than a possible exception are given
to the completion callback.
-### fs.chmodSync(path, mode)
+## fs.chmodSync(path, mode)
Synchronous chmod(2).
-### fs.fchmod(fd, mode, [callback])
+## fs.fchmod(fd, mode, [callback])
Asynchronous fchmod(2). No arguments other than a possible exception
are given to the completion callback.
-### fs.fchmodSync(fd, mode)
+## fs.fchmodSync(fd, mode)
Synchronous fchmod(2).
-### fs.lchmod(path, mode, [callback])
+## fs.lchmod(path, mode, [callback])
Asynchronous lchmod(2). No arguments other than a possible exception
are given to the completion callback.
-### fs.lchmodSync(path, mode)
+## fs.lchmodSync(path, mode)
Synchronous lchmod(2).
-### fs.stat(path, [callback])
+## fs.stat(path, [callback])
Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
`stats` is a [fs.Stats](#fs.Stats) object. See the [fs.Stats](#fs.Stats)
section below for more information.
-### fs.lstat(path, [callback])
+## fs.lstat(path, [callback])
Asynchronous lstat(2). The callback gets two arguments `(err, stats)` where
`stats` is a `fs.Stats` object. `lstat()` is identical to `stat()`, except that if
`path` is a symbolic link, then the link itself is stat-ed, not the file that it
refers to.
-### fs.fstat(fd, [callback])
+## fs.fstat(fd, [callback])
Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where
`stats` is a `fs.Stats` object. `fstat()` is identical to `stat()`, except that
the file to be stat-ed is specified by the file descriptor `fd`.
-### fs.statSync(path)
+## fs.statSync(path)
Synchronous stat(2). Returns an instance of `fs.Stats`.
-### fs.lstatSync(path)
+## fs.lstatSync(path)
Synchronous lstat(2). Returns an instance of `fs.Stats`.
-### fs.fstatSync(fd)
+## fs.fstatSync(fd)
Synchronous fstat(2). Returns an instance of `fs.Stats`.
-### fs.link(srcpath, dstpath, [callback])
+## fs.link(srcpath, dstpath, [callback])
Asynchronous link(2). No arguments other than a possible exception are given to
the completion callback.
-### fs.linkSync(srcpath, dstpath)
+## fs.linkSync(srcpath, dstpath)
Synchronous link(2).
-### fs.symlink(linkdata, path, [type], [callback])
+## fs.symlink(linkdata, path, [type], [callback])
Asynchronous symlink(2). No arguments other than a possible exception are given
to the completion callback.
`type` argument can be either `'dir'` or `'file'` (default is `'file'`). It is only
used on Windows (ignored on other platforms).
-### fs.symlinkSync(linkdata, path, [type])
+## fs.symlinkSync(linkdata, path, [type])
Synchronous symlink(2).
-### fs.readlink(path, [callback])
+## fs.readlink(path, [callback])
Asynchronous readlink(2). The callback gets two arguments `(err,
linkString)`.
-### fs.readlinkSync(path)
+## fs.readlinkSync(path)
Synchronous readlink(2). Returns the symbolic link's string value.
-### fs.realpath(path, [callback])
+## fs.realpath(path, [callback])
Asynchronous realpath(2). The callback gets two arguments `(err,
resolvedPath)`. May use `process.cwd` to resolve relative paths.
-### fs.realpathSync(path)
+## fs.realpathSync(path)
Synchronous realpath(2). Returns the resolved path.
-### fs.unlink(path, [callback])
+## fs.unlink(path, [callback])
Asynchronous unlink(2). No arguments other than a possible exception are given
to the completion callback.
-### fs.unlinkSync(path)
+## fs.unlinkSync(path)
Synchronous unlink(2).
-### fs.rmdir(path, [callback])
+## fs.rmdir(path, [callback])
Asynchronous rmdir(2). No arguments other than a possible exception are given
to the completion callback.
-### fs.rmdirSync(path)
+## fs.rmdirSync(path)
Synchronous rmdir(2).
-### fs.mkdir(path, [mode], [callback])
+## fs.mkdir(path, [mode], [callback])
Asynchronous mkdir(2). No arguments other than a possible exception are given
to the completion callback. `mode` defaults to `0777`.
-### fs.mkdirSync(path, [mode])
+## fs.mkdirSync(path, [mode])
Synchronous mkdir(2).
-### fs.readdir(path, [callback])
+## fs.readdir(path, [callback])
Asynchronous readdir(3). Reads the contents of a directory.
The callback gets two arguments `(err, files)` where `files` is an array of
the names of the files in the directory excluding `'.'` and `'..'`.
-### fs.readdirSync(path)
+## fs.readdirSync(path)
Synchronous readdir(3). Returns an array of filenames excluding `'.'` and
`'..'`.
-### fs.close(fd, [callback])
+## fs.close(fd, [callback])
Asynchronous close(2). No arguments other than a possible exception are given
to the completion callback.
-### fs.closeSync(fd)
+## fs.closeSync(fd)
Synchronous close(2).
-### fs.open(path, flags, [mode], [callback])
+## fs.open(path, flags, [mode], [callback])
Asynchronous file open. See open(2). `flags` can be:
@@ -270,31 +270,31 @@ The file is created if it does not exist.
`mode` defaults to `0666`. The callback gets two arguments `(err, fd)`.
-### fs.openSync(path, flags, [mode])
+## fs.openSync(path, flags, [mode])
Synchronous open(2).
-### fs.utimes(path, atime, mtime, [callback])
-### fs.utimesSync(path, atime, mtime)
+## fs.utimes(path, atime, mtime, [callback])
+## fs.utimesSync(path, atime, mtime)
Change file timestamps of the file referenced by the supplied path.
-### fs.futimes(fd, atime, mtime, [callback])
-### fs.futimesSync(fd, atime, mtime)
+## fs.futimes(fd, atime, mtime, [callback])
+## fs.futimesSync(fd, atime, mtime)
Change the file timestamps of a file referenced by the supplied file
descriptor.
-### fs.fsync(fd, [callback])
+## fs.fsync(fd, [callback])
Asynchronous fsync(2). No arguments other than a possible exception are given
to the completion callback.
-### fs.fsyncSync(fd)
+## fs.fsyncSync(fd)
Synchronous fsync(2).
-### fs.write(fd, buffer, offset, length, position, [callback])
+## fs.write(fd, buffer, offset, length, position, [callback])
Write `buffer` to the file specified by `fd`.
@@ -312,17 +312,17 @@ 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.
-### fs.writeSync(fd, buffer, offset, length, position)
+## fs.writeSync(fd, buffer, offset, length, position)
Synchronous version of buffer-based `fs.write()`. Returns the number of bytes
written.
-### fs.writeSync(fd, str, position, [encoding])
+## fs.writeSync(fd, str, position, [encoding])
Synchronous version of string-based `fs.write()`. `encoding` defaults to
`'utf8'`. Returns the number of _bytes_ written.
-### fs.read(fd, buffer, offset, length, position, [callback])
+## fs.read(fd, buffer, offset, length, position, [callback])
Read data from the file specified by `fd`.
@@ -337,17 +337,17 @@ If `position` is `null`, data will be read from the current file position.
The callback is given the three arguments, `(err, bytesRead, buffer)`.
-### fs.readSync(fd, buffer, offset, length, position)
+## fs.readSync(fd, buffer, offset, length, position)
Synchronous version of buffer-based `fs.read`. Returns the number of
`bytesRead`.
-### fs.readSync(fd, length, position, encoding)
+## fs.readSync(fd, length, position, encoding)
Synchronous version of string-based `fs.read`. Returns the number of
`bytesRead`.
-### fs.readFile(filename, [encoding], [callback])
+## fs.readFile(filename, [encoding], [callback])
Asynchronously reads the entire contents of a file. Example:
@@ -362,7 +362,7 @@ contents of the file.
If no encoding is specified, then the raw buffer is returned.
-### fs.readFileSync(filename, [encoding])
+## fs.readFileSync(filename, [encoding])
Synchronous version of `fs.readFile`. Returns the contents of the `filename`.
@@ -370,7 +370,7 @@ If `encoding` is specified then this function returns a string. Otherwise it
returns a buffer.
-### fs.writeFile(filename, data, [encoding], [callback])
+## fs.writeFile(filename, data, [encoding], [callback])
Asynchronously writes data to a file, replacing the file if it already exists.
`data` can be a string or a buffer. The `encoding` argument is ignored if
@@ -383,11 +383,11 @@ Example:
console.log('It\'s saved!');
});
-### fs.writeFileSync(filename, data, [encoding])
+## fs.writeFileSync(filename, data, [encoding])
The synchronous version of `fs.writeFile`.
-### fs.watchFile(filename, [options], listener)
+## fs.watchFile(filename, [options], listener)
Watch for changes on `filename`. The callback `listener` will be called each
time the file is accessed.
@@ -413,11 +413,11 @@ If you want to be notified when the file was modified, not just accessed
you need to compare `curr.mtime` and `prev.mtime`.
-### fs.unwatchFile(filename)
+## fs.unwatchFile(filename)
Stop watching for changes on `filename`.
-### fs.watch(filename, [options], listener)
+## fs.watch(filename, [options], listener)
Watch for changes on `filename`, where `filename` is either a file or a
directory. The returned object is [fs.FSWatcher](#fs.FSWatcher).
@@ -447,7 +447,7 @@ callback, and have some fallback logic if it is null.
}
});
-## fs.Stats
+## Class: fs.Stats
Objects returned from `fs.stat()`, `fs.lstat()` and `fs.fstat()` and their
synchronous counterparts are of this type.
@@ -490,17 +490,8 @@ be found in the [MDN JavaScript Reference][MDN-Date] page.
[MDN-Date]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date
[MDN-Date-getTime]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date/getTime
-## fs.ReadStream
-`ReadStream` is a [Readable Stream](streams.html#readable_Stream).
-
-### Event: 'open'
-
-`function (fd) { }`
-
- `fd` is the file descriptor used by the ReadStream.
-
-### fs.createReadStream(path, [options])
+## fs.createReadStream(path, [options])
Returns a new ReadStream object (See `Readable Stream`).
@@ -522,22 +513,18 @@ An example to read the last 10 bytes of a file which is 100 bytes long:
fs.createReadStream('sample.txt', {start: 90, end: 99});
-## fs.WriteStream
+## Class: fs.ReadStream
-`WriteStream` is a [Writable Stream](streams.html#writable_Stream).
+`ReadStream` is a [Readable Stream](stream.html#readable_stream).
### Event: 'open'
`function (fd) { }`
- `fd` is the file descriptor used by the WriteStream.
-
-### file.bytesWritten
+ `fd` is the file descriptor used by the ReadStream.
-The number of bytes written so far. Does not include data that is still queued
-for writing.
-### fs.createWriteStream(path, [options])
+## fs.createWriteStream(path, [options])
Returns a new WriteStream object (See `Writable Stream`).
@@ -552,22 +539,38 @@ some position past the beginning of the file. Modifying a file rather
than replacing it may require a `flags` mode of `r+` rather than the
default mode `w`.
-## fs.FSWatcher
+## fs.WriteStream
+
+`WriteStream` is a [Writable Stream](stream.html#writable_stream).
+
+### Event: 'open'
+
+`function (fd) { }`
+
+ `fd` is the file descriptor used by the WriteStream.
+
+### file.bytesWritten
+
+The number of bytes written so far. Does not include data that is still queued
+for writing.
+
+## Class: fs.FSWatcher
Objects returned from `fs.watch()` are of this type.
-#### watcher.close()
+### watcher.close()
Stop watching for changes on the given `fs.FSWatcher`.
-#### Event: 'change'
+### Event: 'change'
-`function (event, filename) {}`
+* `event` {String} The type of fs change
+* `filename` {String} The filename that changed (if relevant/available)
Emitted when something changes in a watched directory or file.
See more details in [fs.watch](#fs.watch).
-#### Event: 'error'
+### Event: 'error'
`function (exception) {}`
diff --git a/doc/api/globals.markdown b/doc/api/globals.markdown
index cc457a7c42..b0e10102f6 100644
--- a/doc/api/globals.markdown
+++ b/doc/api/globals.markdown
@@ -1,30 +1,50 @@
-## Global Objects
+# Global Objects
+
+
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
+## global
+
+
-The global namespace object.
+* {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
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.
-### process
+## process
+
+
+
+* {Object}
The process object. See the [process object](process.html#process) section.
-### console
+## console
+
+
+
+* {Object}
Used to print to stdout and stderr. See the [stdio](stdio.html) section.
-### Buffer
+## Buffer
+
+
+
+* {Object}
+
+Used to handle binary data. See the [buffer section](buffer.html).
+
+## require()
-Used to handle binary data. See the [buffers](buffers.html) section.
+
-### require()
+* {Function}
To require modules. See the [Modules](modules.html#modules) section.
`require` isn't actually a global but rather local to each module.
@@ -37,11 +57,16 @@ but rather than loading the module, just return the resolved filename.
### require.cache
+* {Object}
+
Modules are cached in this object when they are required. By deleting a key
value from this object, the next `require` will reload the module.
+## __filename
+
+
-### __filename
+* {String}
The filename of the code being executed. This is the resolved absolute path
of this code file. For a main program this is not necessarily the same
@@ -55,7 +80,11 @@ Example: running `node example.js` from `/Users/mjr`
`__filename` isn't actually a global but rather local to each module.
-### __dirname
+## __dirname
+
+
+
+* {String}
The name of the directory that the currently executing script resides in.
@@ -67,7 +96,11 @@ Example: running `node example.js` from `/Users/mjr`
`__dirname` isn't actually a global but rather local to each module.
-### module
+## module
+
+
+
+* {Object}
A reference to the current module. In particular
`module.exports` is the same as the `exports` object. See `src/node.js`
@@ -75,7 +108,9 @@ for more information.
`module` isn't actually a global but rather local to each module.
-### exports
+## exports
+
+
An object which is shared between all instances of the current module and
made accessible through `require()`.
@@ -83,9 +118,16 @@ made accessible through `require()`.
for more information.
`exports` isn't actually a global but rather local to each module.
-### setTimeout(cb, ms)
-### clearTimeout(t)
-### setInterval(cb, ms)
-### clearInterval(t)
+See the [module system documentation](modules.html) for more
+information.
+
+See the [module section](modules.html) for more information.
+
+## setTimeout(cb, ms)
+## clearTimeout(t)
+## setInterval(cb, ms)
+## clearInterval(t)
+
+
The timer functions are global variables. See the [timers](timers.html) section.
diff --git a/doc/api/http.markdown b/doc/api/http.markdown
index e5cb91e482..33c92ece4b 100644
--- a/doc/api/http.markdown
+++ b/doc/api/http.markdown
@@ -1,4 +1,4 @@
-## HTTP
+# HTTP
To use the HTTP server and client one must `require('http')`.
@@ -23,7 +23,14 @@ parsing only. It parses a message into headers and body but it does not
parse the actual headers or the body.
-## http.Server
+## http.createServer([requestListener])
+
+Returns a new web server object.
+
+The `requestListener` is a function which is automatically
+added to the `'request'` event.
+
+## Class: http.Server
This is an `EventEmitter` with the following events:
@@ -88,13 +95,6 @@ sent to the server on that socket.
If a client connection emits an 'error' event - it will forwarded here.
-### http.createServer([requestListener])
-
-Returns a new web server object.
-
-The `requestListener` is a function which is automatically
-added to the `'request'` event.
-
### server.listen(port, [hostname], [callback])
Begin accepting connections on the specified port and hostname. If the
@@ -123,12 +123,12 @@ Stops the server from accepting new connections.
See [net.Server.close()](net.html#server.close).
-## http.ServerRequest
+## Class: http.ServerRequest
This object is created internally by a HTTP server -- not by
the user -- and passed as the first argument to a `'request'` listener.
-The request implements the [Readable Stream](streams.html#readable_Stream)
+The request implements the [Readable Stream](stream.html#readable_stream)
interface. This is an `EventEmitter` with the following events:
### Event: 'data'
@@ -137,7 +137,7 @@ interface. This is an `EventEmitter` with the following events:
Emitted when a piece of the message body is received. The chunk is a string if
an encoding has been set with `request.setEncoding()`, otherwise it's a
-[Buffer](buffers.html).
+[Buffer](buffer.html).
Note that the __data will be lost__ if there is no listener when a
`ServerRequest` emits a `'data'` event.
@@ -243,12 +243,12 @@ authentication details.
-## http.ServerResponse
+## Class: http.ServerResponse
This object is created internally by a HTTP server--not by the user. It is
passed as the second parameter to the `'request'` event.
-The response implements the [Writable Stream](streams.html#writable_Stream)
+The response implements the [Writable Stream](stream.html#writable_stream)
interface. This is an `EventEmitter` with the following events:
### Event: 'close'
@@ -491,7 +491,7 @@ Example:
});
-## http.Agent
+## Class: http.Agent
In node 0.5.3+ there is a new implementation of the HTTP Agent which is used
for pooling sockets used in HTTP client requests.
@@ -522,10 +522,6 @@ Alternatively, you could just opt out of pooling entirely using `agent:false`:
// Do stuff
})
-## http.globalAgent
-
-Global instance of Agent which is used as the default for all http client requests.
-
### agent.maxSockets
By default set to 5. Determines how many concurrent sockets the agent can have
@@ -541,8 +537,13 @@ modify.
An object which contains queues of requests that have not yet been assigned to
sockets. Do not modify.
+## http.globalAgent
+
+Global instance of Agent which is used as the default for all http client
+requests.
+
-## http.ClientRequest
+## Class: http.ClientRequest
This object is created internally and returned from `http.request()`. It
represents an _in-progress_ request whose header has already been queued. The
@@ -582,7 +583,7 @@ event, the entire body will be caught.
Note: Node does not check whether Content-Length and the length of the body
which has been transmitted are equal or not.
-The request implements the [Writable Stream](streams.html#writable_Stream)
+The request implements the [Writable Stream](stream.html#writable_stream)
interface. This is an `EventEmitter` with the following events:
### Event 'response'
@@ -672,8 +673,7 @@ server--in that case it is suggested to use the
`['Transfer-Encoding', 'chunked']` header line when
creating the request.
-The `chunk` argument should be an array of integers
-or a string.
+The `chunk` argument should be a [buffer](buffer.html) or a string.
The `encoding` argument is optional and only applies when `chunk` is a string.
Defaults to `'utf8'`.
@@ -715,7 +715,7 @@ will be called.
This object is created when making a request with `http.request()`. It is
passed to the `'response'` event of the request object.
-The response implements the [Readable Stream](streams.html#readable_Stream)
+The response implements the [Readable Stream](stream.html#readable_stream)
interface. This is an `EventEmitter` with the following events:
diff --git a/doc/api/https.markdown b/doc/api/https.markdown
index 0c019349b4..1216ccd469 100644
--- a/doc/api/https.markdown
+++ b/doc/api/https.markdown
@@ -1,9 +1,9 @@
-## HTTPS
+# HTTPS
HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a
separate module.
-## https.Server
+## Class: https.Server
This class is a subclass of `tls.Server` and emits events same as
`http.Server`. See `http.Server` for more information.
@@ -152,7 +152,7 @@ Example:
});
-## https.Agent
+## Class: https.Agent
An Agent object for HTTPS similar to [http.Agent](http.html#http.Agent).
See [https.request()](#https.request) for more information.
diff --git a/doc/api/modules.markdown b/doc/api/modules.markdown
index 7d78610ed1..4f2426a428 100644
--- a/doc/api/modules.markdown
+++ b/doc/api/modules.markdown
@@ -1,4 +1,6 @@
-## Modules
+# Modules
+
+
Node has a simple module loading system. In Node, files and modules are in
one-to-one correspondence. As an example, `foo.js` loads the module
@@ -30,7 +32,11 @@ Variables
local to the module will be private. In this example the variable `PI` is
private to `circle.js`.
-### Cycles
+The module system is implemented in the `require("module")` module.
+
+## Cycles
+
+
When there are circular `require()` calls, a module might not be
done being executed when it is returned.
@@ -84,7 +90,9 @@ The output of this program would thus be:
If you have cyclic module dependencies in your program, make sure to
plan accordingly.
-### Core Modules
+## Core Modules
+
+
Node has several modules compiled into the binary. These modules are
described in greater detail elsewhere in this documentation.
@@ -95,7 +103,9 @@ Core modules are always preferentially loaded if their identifier is
passed to `require()`. For instance, `require('http')` will always
return the built in HTTP module, even if there is a file by that name.
-### File Modules
+## File Modules
+
+
If the exact filename is not found, then node will attempt to load the
required filename with the added extension of `.js`, `.json`, and then `.node`.
@@ -115,7 +125,9 @@ That is, `circle.js` must be in the same directory as `foo.js` for
Without a leading '/' or './' to indicate a file, the module is either a
"core module" or is loaded from a `node_modules` folder.
-### Loading from `node_modules` Folders
+## Loading from `node_modules` Folders
+
+
If the module identifier passed to `require()` is not a native module,
and does not begin with `'/'`, `'../'`, or `'./'`, then node starts at the
@@ -137,7 +149,9 @@ this order:
This allows programs to localize their dependencies, so that they do not
clash.
-### Folders as Modules
+## Folders as Modules
+
+
It is convenient to organize programs and libraries into self-contained
directories, and then provide a single entry point to that library.
@@ -165,7 +179,9 @@ example, then `require('./some-library')` would attempt to load:
* `./some-library/index.js`
* `./some-library/index.node`
-### Caching
+## Caching
+
+
Modules are cached after the first time they are loaded. This means
(among other things) that every call to `require('foo')` will get
@@ -179,7 +195,9 @@ dependencies to be loaded even when they would cause cycles.
If you want to have a module execute code multiple times, then export a
function, and call that function.
-#### Module Caching Caveats
+### Module Caching Caveats
+
+
Modules are cached based on their resolved filename. Since modules may
resolve to a different filename based on the location of the calling
@@ -187,8 +205,22 @@ module (loading from `node_modules` folders), it is not a *guarantee*
that `require('foo')` will always return the exact same object, if it
would resolve to different files.
+## The `module` Object
+
+
+
+
+* {Object}
+
+In each module, the `module` free variable is a reference to the object
+representing the current module. In particular
+`module.exports` is the same as the `exports` object.
+`module` isn't actually a global but rather local to each module.
+
### module.exports
+* {Object}
+
The `exports` object is created by the Module system. Sometimes this is not
acceptable, many want their module to be an instance of some class. To do this
assign the desired export object to `module.exports`. For example suppose we
@@ -227,7 +259,10 @@ y.js:
console.log(x.a);
-### module.require
+### module.require(id)
+
+* `id` {String}
+* Return: {Object} `exports` from the resolved module
The `module.require` method provides a way to load a module as if
`require()` was called from the original module.
@@ -238,7 +273,47 @@ typically *only* available within a specific module's code, it must be
explicitly exported in order to be used.
-### All Together...
+### module.id
+
+* {String}
+
+The identifier for the module. Typically this is the fully resolved
+filename.
+
+
+### module.filename
+
+* {String}
+
+The fully resolved filename to the module.
+
+
+### module.loaded
+
+* {Boolean}
+
+Whether or not the module is done loading, or is in the process of
+loading.
+
+
+### module.parent
+
+* {Module Object}
+
+The module that required this one.
+
+
+### module.children
+
+* {Array}
+
+The module objects required by this one.
+
+
+
+## All Together...
+
+
To get the exact filename that will be loaded when `require()` is called, use
the `require.resolve()` function.
@@ -287,7 +362,9 @@ in pseudocode of what require.resolve does:
c. let I = I - 1
6. return DIRS
-### Loading from the global folders
+## Loading from the global folders
+
+
If the `NODE_PATH` environment variable is set to a colon-delimited list
of absolute paths, then node will search those paths for modules if they
@@ -307,7 +384,9 @@ These are mostly for historic reasons. You are highly encouraged to
place your dependencies locally in `node_modules` folders. They will be
loaded faster, and more reliably.
-### Accessing the main module
+## Accessing the main module
+
+
When a file is run directly from Node, `require.main` is set to its
`module`. That means that you can determine whether a file has been run
@@ -324,6 +403,8 @@ by checking `require.main.filename`.
## Addenda: Package Manager Tips
+
+
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
diff --git a/doc/api/net.markdown b/doc/api/net.markdown
index 49cf5b049c..8c3654df63 100644
--- a/doc/api/net.markdown
+++ b/doc/api/net.markdown
@@ -1,10 +1,10 @@
-## net
+# net
The `net` module provides you with an asynchronous network wrapper. It contains
methods for creating both servers and clients (called streams). You can include
this module with `require('net');`
-### net.createServer([options], [connectionListener])
+## net.createServer([options], [connectionListener])
Creates a new TCP server. The `connectionListener` argument is
automatically set as a listener for the ['connection'](#event_connection_)
@@ -49,8 +49,8 @@ Use `nc` to connect to a UNIX domain socket server:
nc -U /tmp/echo.sock
-### net.connect(arguments...)
-### net.createConnection(arguments...)
+## net.connect(arguments...)
+## net.createConnection(arguments...)
Construct a new socket object and opens a socket to the given location. When
the socket is established the ['connect'](#event_connect_) event will be
@@ -92,14 +92,12 @@ changed to
var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
----
-
-### net.Server
+## Class: net.Server
This class is used to create a TCP or UNIX server.
A server is a `net.Socket` that can listen for new incoming connections.
-#### server.listen(port, [host], [listeningListener])
+### server.listen(port, [host], [listeningListener])
Begin accepting connections on the specified `port` and `host`. If the
`host` is omitted, the server will accept connections directed to any
@@ -127,7 +125,7 @@ would be to wait a second and then try again. This can be done with
(Note: All sockets in Node set `SO_REUSEADDR` already)
-#### server.listen(path, [listeningListener])
+### server.listen(path, [listeningListener])
Start a UNIX socket server listening for connections on the given `path`.
@@ -136,14 +134,14 @@ This function is asynchronous. When the server has been bound,
the last parameter `listeningListener` will be added as an listener for the
['listening'](#event_listening_) event.
-#### server.close()
+### server.close()
Stops the server from accepting new connections. This function is
asynchronous, the server is finally closed when the server emits a `'close'`
event.
-#### server.address()
+### server.address()
Returns the bound address and port of the server as reported by the operating system.
Useful to find which port was assigned when giving getting an OS-assigned address.
@@ -163,54 +161,48 @@ Example:
Don't call `server.address()` until the `'listening'` event has been emitted.
-#### server.maxConnections
+### server.maxConnections
Set this property to reject connections when the server's connection count gets
high.
-#### server.connections
+### server.connections
The number of concurrent connections on the server.
`net.Server` is an `EventEmitter` with the following events:
-#### Event: 'listening'
-
-`function () {}`
+### Event: 'listening'
Emitted when the server has been bound after calling `server.listen`.
-#### Event: 'connection'
+### Event: 'connection'
-`function (socket) {}`
+* {Socket object} The connection object
Emitted when a new connection is made. `socket` is an instance of
`net.Socket`.
-#### Event: 'close'
-
-`function () {}`
+### Event: 'close'
Emitted when the server closes.
-#### Event: 'error'
+### Event: 'error'
-`function (exception) {}`
+* {Error Object}
Emitted when an error occurs. The `'close'` event will be called directly
following this event. See example in discussion of `server.listen`.
----
-
-### net.Socket
+## Class: net.Socket
This object is an abstraction of a TCP or UNIX socket. `net.Socket`
instances implement a duplex Stream interface. They can be created by the
user and used as a client (with `connect()`) or they can be created by Node
and passed to the user through the `'connection'` event of a server.
-#### new net.Socket([options])
+### new net.Socket([options])
Construct a new socket object.
@@ -225,8 +217,8 @@ Construct a new socket object.
specified underlying protocol. It can be `'tcp4'`, `'tcp6'`, or `'unix'`.
About `allowHalfOpen`, refer to `createServer()` and `'end'` event.
-#### socket.connect(port, [host], [connectListener])
-#### socket.connect(path, [connectListener])
+### socket.connect(port, [host], [connectListener])
+### socket.connect(path, [connectListener])
Opens the connection for a given socket. If `port` and `host` are given,
then the socket will be opened as a TCP socket, if `host` is omitted,
@@ -246,7 +238,7 @@ The `connectListener` parameter will be added as an listener for the
['connect'](#event_connect_) event.
-#### socket.bufferSize
+### socket.bufferSize
`net.Socket` has the property that `socket.write()` always works. This is to
help users get up and running quickly. The computer cannot always keep up
@@ -265,18 +257,18 @@ Users who experience large or growing `bufferSize` should attempt to
"throttle" the data flows in their program with `pause()` and `resume()`.
-#### socket.setEncoding([encoding])
+### socket.setEncoding([encoding])
Sets the encoding (either `'ascii'`, `'utf8'`, or `'base64'`) for data that is
received. Defaults to `null`.
-#### socket.setSecure()
+### socket.setSecure()
This function has been removed in v0.3. It used to upgrade the connection to
SSL/TLS. See the [TLS section](tls.html#tLS_) for the new API.
-#### socket.write(data, [encoding], [callback])
+### socket.write(data, [encoding], [callback])
Sends data on the socket. The second parameter specifies the encoding in the
case of a string--it defaults to UTF8 encoding.
@@ -288,12 +280,12 @@ buffer. Returns `false` if all or part of the data was queued in user memory.
The optional `callback` parameter will be executed when the data is finally
written out - this may not be immediately.
-#### socket.write(data, [encoding], [callback])
+### socket.write(data, [encoding], [callback])
Write data with the optional encoding. The callback will be made when the
data is flushed to the kernel.
-#### socket.end([data], [encoding])
+### socket.end([data], [encoding])
Half-closes the socket. i.e., it sends a FIN packet. It is possible the
server will still send some data.
@@ -301,21 +293,21 @@ server will still send some data.
If `data` is specified, it is equivalent to calling
`socket.write(data, encoding)` followed by `socket.end()`.
-#### socket.destroy()
+### socket.destroy()
Ensures that no more I/O activity happens on this socket. Only necessary in
case of errors (parse error or so).
-#### socket.pause()
+### socket.pause()
Pauses the reading of data. That is, `'data'` events will not be emitted.
Useful to throttle back an upload.
-#### socket.resume()
+### socket.resume()
Resumes reading after a call to `pause()`.
-#### socket.setTimeout(timeout, [callback])
+### socket.setTimeout(timeout, [callback])
Sets the socket to timeout after `timeout` milliseconds of inactivity on
the socket. By default `net.Socket` do not have a timeout.
@@ -329,14 +321,14 @@ If `timeout` is 0, then the existing idle timeout is disabled.
The optional `callback` parameter will be added as a one time listener for the
`'timeout'` event.
-#### socket.setNoDelay([noDelay])
+### socket.setNoDelay([noDelay])
Disables the Nagle algorithm. By default TCP connections use the Nagle
algorithm, they buffer data before sending it off. Setting `true` for
`noDelay` will immediately fire off data each time `socket.write()` is called.
`noDelay` defaults to `true`.
-#### socket.setKeepAlive([enable], [initialDelay])
+### socket.setKeepAlive([enable], [initialDelay])
Enable/disable keep-alive functionality, and optionally set the initial
delay before the first keepalive probe is sent on an idle socket.
@@ -347,55 +339,51 @@ data packet received and the first keepalive probe. Setting 0 for
initialDelay will leave the value unchanged from the default
(or previous) setting. Defaults to `0`.
-#### socket.address()
+### socket.address()
Returns the bound address and port of the socket as reported by the operating
system. Returns an object with two properties, e.g.
`{"address":"192.168.57.1", "port":62053}`
-#### socket.remoteAddress
+### socket.remoteAddress
The string representation of the remote IP address. For example,
`'74.125.127.100'` or `'2001:4860:a005::68'`.
-#### socket.remotePort
+### socket.remotePort
The numeric representation of the remote port. For example,
`80` or `21`.
-#### socket.bytesRead
+### socket.bytesRead
The amount of received bytes.
-#### socket.bytesWritten
+### socket.bytesWritten
The amount of bytes sent.
`net.Socket` instances are EventEmitters with the following events:
-#### Event: 'connect'
-
-`function () { }`
+### Event: 'connect'
Emitted when a socket connection is successfully established.
See `connect()`.
-#### Event: 'data'
+### Event: 'data'
-`function (data) { }`
+* {Buffer object}
Emitted when data is received. The argument `data` will be a `Buffer` or
`String`. Encoding of data is set by `socket.setEncoding()`.
-(See the [Readable Stream](streams.html#readable_Stream) section for more
+(See the [Readable Stream](stream.html#readable_stream) section for more
information.)
Note that the __data will be lost__ if there is no listener when a `Socket`
emits a `'data'` event.
-#### Event: 'end'
-
-`function () { }`
+### Event: 'end'
Emitted when the other end of the socket sends a FIN packet.
@@ -406,9 +394,7 @@ its side allowing the user to write arbitrary amounts of data, with the
caveat that the user is required to `end()` their side now.
-#### Event: 'timeout'
-
-`function () { }`
+### Event: 'timeout'
Emitted if the socket times out from inactivity. This is only to notify that
the socket has been idle. The user must manually close the connection.
@@ -416,44 +402,38 @@ the socket has been idle. The user must manually close the connection.
See also: `socket.setTimeout()`
-#### Event: 'drain'
-
-`function () { }`
+### Event: 'drain'
Emitted when the write buffer becomes empty. Can be used to throttle uploads.
See also: the return values of `socket.write()`
-#### Event: 'error'
+### Event: 'error'
-`function (exception) { }`
+* {Error object}
Emitted when an error occurs. The `'close'` event will be called directly
following this event.
-#### Event: 'close'
+### Event: 'close'
-`function (had_error) { }`
+* `had_error` {Boolean} true if the socket had a transmission error
Emitted once the socket is fully closed. The argument `had_error` is a boolean
which says if the socket was closed due to a transmission error.
----
-
-### net.isIP
-
-#### net.isIP(input)
+## net.isIP(input)
Tests if input is an IP address. Returns 0 for invalid strings,
returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses.
-#### net.isIPv4(input)
+## net.isIPv4(input)
Returns true if input is a version 4 IP address, otherwise returns false.
-#### net.isIPv6(input)
+## net.isIPv6(input)
Returns true if input is a version 6 IP address, otherwise returns false.
diff --git a/doc/api/os.markdown b/doc/api/os.markdown
index 02823acfff..04fd5ace5f 100644
--- a/doc/api/os.markdown
+++ b/doc/api/os.markdown
@@ -1,44 +1,46 @@
-## os Module
+# os
+
+Provides a few basic operating-system related utility functions.
Use `require('os')` to access this module.
-### os.hostname()
+## os.hostname()
Returns the hostname of the operating system.
-### os.type()
+## os.type()
Returns the operating system name.
-### os.platform()
+## os.platform()
Returns the operating system platform.
-### os.arch()
+## os.arch()
Returns the operating system CPU architecture.
-### os.release()
+## os.release()
Returns the operating system release.
-### os.uptime()
+## os.uptime()
Returns the system uptime in seconds.
-### os.loadavg()
+## os.loadavg()
Returns an array containing the 1, 5, and 15 minute load averages.
-### os.totalmem()
+## os.totalmem()
Returns the total amount of system memory in bytes.
-### os.freemem()
+## os.freemem()
Returns the amount of free system memory in bytes.
-### os.cpus()
+## os.cpus()
Returns an array of objects containing information about each CPU/core installed: model, speed (in MHz), and times (an object containing the number of CPU ticks spent in: user, nice, sys, idle, and irq).
@@ -109,7 +111,7 @@ Example inspection of os.cpus:
idle: 1072572010,
irq: 30 } } ]
-### os.networkInterfaces()
+## os.networkInterfaces()
Get a list of network interfaces:
diff --git a/doc/api/path.markdown b/doc/api/path.markdown
index ba48bd29c8..06b6d21779 100644
--- a/doc/api/path.markdown
+++ b/doc/api/path.markdown
@@ -1,4 +1,4 @@
-## Path
+# Path
This module contains utilities for handling and transforming file
paths. Almost all these methods perform only string transformations.
@@ -9,7 +9,7 @@ logically be found in the fs module as they do access the file system.
Use `require('path')` to use this module. The following methods are provided:
-### path.normalize(p)
+## path.normalize(p)
Normalize a string path, taking care of `'..'` and `'.'` parts.
@@ -23,7 +23,7 @@ Example:
// returns
'/foo/bar/baz/asdf'
-### path.join([path1], [path2], [...])
+## path.join([path1], [path2], [...])
Join all arguments together and normalize the resulting path.
Non-string arguments are ignored.
@@ -38,7 +38,7 @@ Example:
// returns
'foo/bar'
-### path.resolve([from ...], to)
+## path.resolve([from ...], to)
Resolves `to` to an absolute path.
@@ -77,7 +77,7 @@ Examples:
// if currently in /home/myself/node, it returns
'/home/myself/node/wwwroot/static_files/gif/image.gif'
-### path.relative(from, to)
+## path.relative(from, to)
Solve the relative path from `from` to `to`.
@@ -97,7 +97,7 @@ Examples:
// returns
'../../impl/bbb'
-### path.dirname(p)
+## path.dirname(p)
Return the directory name of a path. Similar to the Unix `dirname` command.
@@ -107,7 +107,7 @@ Example:
// returns
'/foo/bar/baz/asdf'
-### path.basename(p, [ext])
+## path.basename(p, [ext])
Return the last portion of a path. Similar to the Unix `basename` command.
@@ -121,7 +121,7 @@ Example:
// returns
'quux'
-### path.extname(p)
+## path.extname(p)
Return the extension of the path, from the last '.' to end of string
in the last portion of the path. If there is no '.' in the last portion
diff --git a/doc/api/process.markdown b/doc/api/process.markdown
index 57a139f298..66118f9270 100644
--- a/doc/api/process.markdown
+++ b/doc/api/process.markdown
@@ -1,12 +1,12 @@
-## process
+# process
+
+
The `process` object is a global object and can be accessed from anywhere.
It is an instance of `EventEmitter`.
-### Event: 'exit'
-
-`function () {}`
+## Event: 'exit'
Emitted when the process is about to exit. This is a good hook to perform
constant time checks of the module's state (like for unit tests). The main
@@ -22,9 +22,7 @@ Example of listening for `exit`:
console.log('About to exit.');
});
-### Event: 'uncaughtException'
-
-`function (err) { }`
+## Event: 'uncaughtException'
Emitted when an exception bubbles all the way back to the event loop. If a
listener is added for this exception, the default action (which is to print
@@ -50,9 +48,10 @@ your program's flow. Especially for server programs that are designed to
stay running forever, `uncaughtException` can be a useful safety mechanism.
-### Signal Events
+## Signal Events
-`function () {}`
+
+
Emitted when the processes receives a signal. See sigaction(2) for a list of
standard POSIX signal names such as SIGINT, SIGUSR1, etc.
@@ -70,7 +69,7 @@ An easy way to send the `SIGINT` signal is with `Control-C` in most terminal
programs.
-### process.stdout
+## process.stdout
A `Writable Stream` to `stdout`.
@@ -86,7 +85,7 @@ that they refer to regular files or TTY file descriptors. In the case they
refer to pipes, they are non-blocking like other streams.
-### process.stderr
+## process.stderr
A writable stream to stderr.
@@ -96,7 +95,7 @@ that they refer to regular files or TTY file descriptors. In the case they
refer to pipes, they are non-blocking like other streams.
-### process.stdin
+## process.stdin
A `Readable Stream` for stdin. The stdin stream is paused by default, so one
must call `process.stdin.resume()` to read from it.
@@ -115,7 +114,7 @@ Example of opening standard input and listening for both events:
});
-### process.argv
+## process.argv
An array containing the command line arguments. The first element will be
'node', the second element will be the name of the JavaScript file. The
@@ -136,7 +135,7 @@ This will generate:
4: four
-### process.execPath
+## process.execPath
This is the absolute pathname of the executable that started the process.
@@ -145,7 +144,7 @@ Example:
/usr/local/bin/node
-### process.chdir(directory)
+## process.chdir(directory)
Changes the current working directory of the process or throws an exception if that fails.
@@ -160,19 +159,19 @@ Changes the current working directory of the process or throws an exception if t
-### process.cwd()
+## process.cwd()
Returns the current working directory of the process.
console.log('Current directory: ' + process.cwd());
-### process.env
+## process.env
An object containing the user environment. See environ(7).
-### process.exit([code])
+## process.exit([code])
Ends the process with the specified `code`. If omitted, exit uses the
'success' code `0`.
@@ -184,7 +183,7 @@ To exit with a 'failure' code:
The shell that executed node should see the exit code as 1.
-### process.getgid()
+## process.getgid()
Gets the group identity of the process. (See getgid(2).)
This is the numerical group id, not the group name.
@@ -192,7 +191,7 @@ This is the numerical group id, not the group name.
console.log('Current gid: ' + process.getgid());
-### process.setgid(id)
+## process.setgid(id)
Sets the group identity of the process. (See setgid(2).) This accepts either
a numerical ID or a groupname string. If a groupname is specified, this method
@@ -208,7 +207,7 @@ blocks while resolving it to a numerical ID.
}
-### process.getuid()
+## process.getuid()
Gets the user identity of the process. (See getuid(2).)
This is the numerical userid, not the username.
@@ -216,7 +215,7 @@ This is the numerical userid, not the username.
console.log('Current uid: ' + process.getuid());
-### process.setuid(id)
+## process.setuid(id)
Sets the user identity of the process. (See setuid(2).) This accepts either
a numerical ID or a username string. If a username is specified, this method
@@ -232,13 +231,13 @@ blocks while resolving it to a numerical ID.
}
-### process.version
+## process.version
A compiled-in property that exposes `NODE_VERSION`.
console.log('Version: ' + process.version);
-### process.versions
+## process.versions
A property exposing version strings of node and its dependencies.
@@ -253,14 +252,14 @@ Will output:
openssl: '1.0.0e-fips' }
-### process.installPrefix
+## process.installPrefix
A compiled-in property that exposes `NODE_PREFIX`.
console.log('Prefix: ' + process.installPrefix);
-### process.kill(pid, [signal])
+## process.kill(pid, [signal])
Send a signal to a process. `pid` is the process id and `signal` is the
string describing the signal to send. Signal names are strings like
@@ -285,32 +284,32 @@ Example of sending a signal to yourself:
process.kill(process.pid, 'SIGHUP');
-### process.pid
+## process.pid
The PID of the process.
console.log('This process is pid ' + process.pid);
-### process.title
+## process.title
Getter/setter to set what is displayed in 'ps'.
-### process.arch
+## process.arch
What processor architecture you're running on: `'arm'`, `'ia32'`, or `'x64'`.
console.log('This processor architecture is ' + process.arch);
-### process.platform
+## process.platform
What platform you're running on. `'linux2'`, `'darwin'`, etc.
console.log('This platform is ' + process.platform);
-### process.memoryUsage()
+## process.memoryUsage()
Returns an object describing the memory usage of the Node process
measured in bytes.
@@ -328,7 +327,7 @@ This will generate:
`heapTotal` and `heapUsed` refer to V8's memory usage.
-### process.nextTick(callback)
+## process.nextTick(callback)
On the next loop around the event loop call this callback.
This is *not* a simple alias to `setTimeout(fn, 0)`, it's much more
@@ -339,7 +338,7 @@ efficient.
});
-### process.umask([mask])
+## process.umask([mask])
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
@@ -352,6 +351,6 @@ given, otherwise returns the current mask.
' to ' + newmask.toString(8));
-### process.uptime()
+## process.uptime()
Number of seconds Node has been running.
diff --git a/doc/api/querystring.markdown b/doc/api/querystring.markdown
index 25741804dc..4629550d7a 100644
--- a/doc/api/querystring.markdown
+++ b/doc/api/querystring.markdown
@@ -1,9 +1,11 @@
-## Query String
+# Query String
+
+
This module provides utilities for dealing with query strings.
It provides the following methods:
-### querystring.stringify(obj, [sep], [eq])
+## querystring.stringify(obj, [sep], [eq])
Serialize an object to a query string.
Optionally override the default separator (`'&'`) and assignment (`'='`)
@@ -19,7 +21,7 @@ Example:
// returns
'foo:bar;baz:qux'
-### querystring.parse(str, [sep], [eq])
+## querystring.parse(str, [sep], [eq])
Deserialize a query string to an object.
Optionally override the default separator (`'&'`) and assignment (`'='`)
@@ -31,12 +33,12 @@ Example:
// returns
{ foo: 'bar', baz: ['qux', 'quux'], corge: '' }
-### querystring.escape
+## querystring.escape
The escape function used by `querystring.stringify`,
provided so that it could be overridden if necessary.
-### querystring.unescape
+## querystring.unescape
The unescape function used by `querystring.parse`,
provided so that it could be overridden if necessary.
diff --git a/doc/api/readline.markdown b/doc/api/readline.markdown
index 8310a9925d..bb4cceb524 100644
--- a/doc/api/readline.markdown
+++ b/doc/api/readline.markdown
@@ -1,4 +1,4 @@
-## Readline
+# Readline
To use this module, do `require('readline')`. Readline allows reading of a
stream (such as STDIN) on a line-by-line basis.
@@ -20,7 +20,7 @@ to allow your program to gracefully terminate:
process.stdin.destroy();
});
-### rl.createInterface(input, output, completer)
+## rl.createInterface(input, output, completer)
Takes two streams and creates a readline interface. The `completer` function
is used for autocompletion. When given a substring, it returns `[[substr1,
@@ -38,6 +38,11 @@ Also `completer` can be run in async mode if it accepts two arguments:
var readline = require('readline'),
rl = readline.createInterface(process.stdin, process.stdout);
+## Class: Interface
+
+The class that represents a readline interface with a stdin and stdout
+stream.
+
### rl.setPrompt(prompt, length)
Sets the prompt, for example when you run `node` on the command line, you see
@@ -48,8 +53,6 @@ Sets the prompt, for example when you run `node` on the command line, you see
Readies readline for input from the user, putting the current `setPrompt`
options on a new line, giving the user a new spot to write.
-
-
### rl.question(query, callback)
Prepends the prompt with `query` and invokes `callback` with the user's
diff --git a/doc/api/repl.markdown b/doc/api/repl.markdown
index a55835ae84..bb40a342c3 100644
--- a/doc/api/repl.markdown
+++ b/doc/api/repl.markdown
@@ -1,4 +1,4 @@
-## REPL
+# REPL
A Read-Eval-Print-Loop (REPL) is available both as a standalone program and easily
includable in other programs. REPL provides a way to interactively run
@@ -27,7 +27,7 @@ For example, you could add this to your bashrc file:
alias node="env NODE_NO_READLINE=1 rlwrap node"
-### repl.start([prompt], [stream], [eval], [useGlobal], [ignoreUndefined])
+## repl.start([prompt], [stream], [eval], [useGlobal], [ignoreUndefined])
Starts a REPL with `prompt` as the prompt and `stream` for all I/O. `prompt`
is optional and defaults to `> `. `stream` is optional and defaults to
@@ -77,7 +77,9 @@ By starting a REPL from a Unix socket-based server instead of stdin, you can
connect to a long-running node process without restarting it.
-### REPL Features
+## REPL Features
+
+
Inside the REPL, Control+D will exit. Multi-line expressions can be input.
Tab completion is supported for both global and local variables.
diff --git a/doc/api/stdio.markdown b/doc/api/stdio.markdown
index 7e835b7fc9..0a807bcf80 100644
--- a/doc/api/stdio.markdown
+++ b/doc/api/stdio.markdown
@@ -1,10 +1,14 @@
-## console
+# console
+
+* {Object}
+
+
For printing to stdout and stderr. Similar to the console object functions
provided by most web browsers, here the output is sent to stdout or stderr.
-### console.log()
+## console.log()
Prints to stdout with newline. This function can take multiple arguments in a
`printf()`-like way. Example:
@@ -15,25 +19,25 @@ If formatting elements are not found in the first string then `util.inspect`
is used on each argument.
See [util.format()](util.html#util.format) for more information.
-### console.info()
+## console.info()
Same as `console.log`.
-### console.warn()
-### console.error()
+## console.warn()
+## console.error()
Same as `console.log` but prints to stderr.
-### console.dir(obj)
+## console.dir(obj)
Uses `util.inspect` on `obj` and prints resulting string to stderr.
-### console.time(label)
+## console.time(label)
Mark a time.
-### console.timeEnd(label)
+## console.timeEnd(label)
Finish timer, record output. Example
@@ -44,11 +48,11 @@ Finish timer, record output. Example
console.timeEnd('100-elements');
-### console.trace()
+## console.trace()
Print a stack trace to stderr of the current position.
-### console.assert()
+## console.assert()
Same as `assert.ok()`.
diff --git a/doc/api/streams.markdown b/doc/api/stream.markdown
similarity index 97%
rename from doc/api/streams.markdown
rename to doc/api/stream.markdown
index e11f2dade7..0edf22fbd5 100644
--- a/doc/api/streams.markdown
+++ b/doc/api/stream.markdown
@@ -1,11 +1,15 @@
-## Streams
+# Stream
A stream is an abstract interface implemented by various objects in Node.
For example a request to an HTTP server is a stream, as is stdout. Streams
are readable, writable, or both. All streams are instances of `EventEmitter`.
+You can load up the Stream base class by doing `require('stream')`.
+
## Readable Stream
+
+
A `Readable Stream` has the following methods, members, and events.
### Event: 'data'
@@ -99,6 +103,8 @@ This keeps `process.stdout` open so that "Goodbye" can be written at the end.
## Writable Stream
+
+
A `Writable Stream` has the following methods, members, and events.
### Event: 'drain'
diff --git a/doc/api/synopsis.markdown b/doc/api/synopsis.markdown
index 53efb86fa9..b3b4608553 100644
--- a/doc/api/synopsis.markdown
+++ b/doc/api/synopsis.markdown
@@ -1,4 +1,6 @@
-## Synopsis
+# Synopsis
+
+
An example of a [web server](http.html) written with Node which responds with 'Hello
World':
diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown
index fe89e5c128..72192eacdf 100644
--- a/doc/api/timers.markdown
+++ b/doc/api/timers.markdown
@@ -1,6 +1,9 @@
-## Timers
+# Timers
-### setTimeout(callback, delay, [arg], [...])
+All of the timer functions are globals. You do not need to `require()`
+this module in order to use them.
+
+## setTimeout(callback, delay, [arg], [...])
To schedule execution of a one-time `callback` after `delay` milliseconds. Returns a
`timeoutId` for possible use with `clearTimeout()`. Optionally you can
@@ -11,16 +14,16 @@ It is important to note that your callback will probably not be called in exactl
the callback will fire, nor of the ordering things will fire in. The callback will
be called as close as possible to the time specified.
-### clearTimeout(timeoutId)
+## clearTimeout(timeoutId)
Prevents a timeout from triggering.
-### setInterval(callback, delay, [arg], [...])
+## setInterval(callback, delay, [arg], [...])
To schedule the repeated execution of `callback` every `delay` milliseconds.
Returns a `intervalId` for possible use with `clearInterval()`. Optionally
you can also pass arguments to the callback.
-### clearInterval(intervalId)
+## clearInterval(intervalId)
Stops a interval from triggering.
diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown
index 023c34be64..f79c6203b4 100644
--- a/doc/api/tls.markdown
+++ b/doc/api/tls.markdown
@@ -1,4 +1,4 @@
-## TLS (SSL)
+# TLS (SSL)
Use `require('tls')` to access this module.
@@ -26,7 +26,9 @@ Alternatively you can send the CSR to a Certificate Authority for signing.
(TODO: docs on creating a CA, for now interested users should just look at
`test/fixtures/keys/Makefile` in the Node source code)
-### Client-initiated renegotiation attack mitigation
+## Client-initiated renegotiation attack mitigation
+
+
The TLS protocol lets the client renegotiate certain aspects of the TLS session.
Unfortunately, session renegotiation requires a disproportional amount of
@@ -49,7 +51,9 @@ and tap `R` (that's the letter `R` followed by a carriage return) a few
times.
-### NPN and SNI
+## NPN and SNI
+
+
NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS
handshake extensions allowing you:
@@ -223,6 +227,10 @@ and the cleartext one is used as a replacement for the initial encrypted stream.
`tls.createSecurePair()` returns a SecurePair object with
[cleartext](#tls.CleartextStream) and `encrypted` stream properties.
+## Class: SecurePair
+
+Returned by tls.createSecurePair.
+
### Event: 'secure'
The event is emitted from the SecurePair once the pair has successfully
@@ -232,7 +240,7 @@ Similarly to the checking for the server 'secureConnection' event,
pair.cleartext.authorized should be checked to confirm whether the certificate
used properly authorized.
-## tls.Server
+## Class: tls.Server
This class is a subclass of `net.Server` and has the same methods on it.
Instead of accepting just raw TCP connections, this accepts encrypted
@@ -306,17 +314,17 @@ gets high.
The number of concurrent connections on the server.
-## tls.CleartextStream
+## Class: tls.CleartextStream
This is a stream on top of the *Encrypted* stream that makes it possible to
read/write an encrypted data as a cleartext data.
-This instance implements a duplex [Stream](streams.html#streams) interfaces.
+This instance implements a duplex [Stream](stream.html) interfaces.
It has all the common stream methods and events.
-### Event: 'secureConnect'
+A ClearTextStream is the `clear` member of a SecurePair object.
-`function () {}`
+### 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
diff --git a/doc/api/tty.markdown b/doc/api/tty.markdown
index ed590e8b70..804db3b75e 100644
--- a/doc/api/tty.markdown
+++ b/doc/api/tty.markdown
@@ -1,4 +1,4 @@
-## TTY
+# TTY
Use `require('tty')` to access this module.
@@ -16,23 +16,23 @@ Example:
-### tty.isatty(fd)
+## tty.isatty(fd)
Returns `true` or `false` depending on if the `fd` is associated with a
terminal.
-### tty.setRawMode(mode)
+## tty.setRawMode(mode)
`mode` should be `true` or `false`. This sets the properties of the current
process's stdin fd to act either as a raw device or default.
-### tty.setWindowSize(fd, row, col)
+## tty.setWindowSize(fd, row, col)
This function was removed in v0.6.0.
-### tty.getWindowSize(fd)
+## tty.getWindowSize(fd)
This function was removed in v0.6.0. Use `process.stdout.getWindowSize()`
instead.
diff --git a/doc/api/url.markdown b/doc/api/url.markdown
index a4dbec92cc..cf3d70b42f 100644
--- a/doc/api/url.markdown
+++ b/doc/api/url.markdown
@@ -1,4 +1,4 @@
-## URL
+# URL
This module has utilities for URL resolution and parsing.
Call `require('url')` to use it.
@@ -45,7 +45,7 @@ string will not be in the parsed object. Examples are shown for the URL
The following methods are provided by the URL module:
-### url.parse(urlStr, [parseQueryString], [slashesDenoteHost])
+## url.parse(urlStr, [parseQueryString], [slashesDenoteHost])
Take a URL string, and return an object.
@@ -57,7 +57,7 @@ Pass `true` as the third argument to treat `//foo/bar` as
`{ host: 'foo', pathname: '/bar' }` rather than
`{ pathname: '//foo/bar' }`. Defaults to `false`.
-### url.format(urlObj)
+## url.format(urlObj)
Take a parsed URL object, and return a formatted URL string.
@@ -75,6 +75,6 @@ Take a parsed URL object, and return a formatted URL string.
* `search` is treated the same with or without the leading `?` (question mark)
* `hash` is treated the same with or without the leading `#` (pound sign, anchor)
-### url.resolve(from, to)
+## url.resolve(from, to)
Take a base URL, and a href URL, and resolve them as a browser would for an anchor tag.
diff --git a/doc/api/util.markdown b/doc/api/util.markdown
index fefe22707a..bcade3980b 100644
--- a/doc/api/util.markdown
+++ b/doc/api/util.markdown
@@ -1,10 +1,10 @@
-## util
+# util
These functions are in the module `'util'`. Use `require('util')` to access
them.
-### util.format()
+## util.format()
Returns a formatted string using the first argument as a `printf`-like format.
@@ -35,7 +35,7 @@ Each argument is converted to a string with `util.inspect()`.
util.format(1, 2, 3); // '1 2 3'
-### util.debug(string)
+## util.debug(string)
A synchronous output function. Will block the process and
output `string` immediately to `stderr`.
@@ -43,14 +43,14 @@ output `string` immediately to `stderr`.
require('util').debug('message on stderr');
-### util.log(string)
+## util.log(string)
Output with timestamp on `stdout`.
require('util').log('Timestamped message.');
-### util.inspect(object, [showHidden], [depth], [colors])
+## util.inspect(object, [showHidden], [depth], [colors])
Return a string representation of `object`, which is useful for debugging.
@@ -73,7 +73,7 @@ Example of inspecting all properties of the `util` object:
console.log(util.inspect(util, true, null));
-### util.isArray(object)
+## util.isArray(object)
Returns `true` if the given "object" is an `Array`. `false` otherwise.
@@ -87,7 +87,7 @@ Returns `true` if the given "object" is an `Array`. `false` otherwise.
// false
-### util.isRegExp(object)
+## util.isRegExp(object)
Returns `true` if the given "object" is a `RegExp`. `false` otherwise.
@@ -101,7 +101,7 @@ Returns `true` if the given "object" is a `RegExp`. `false` otherwise.
// false
-### util.isDate(object)
+## util.isDate(object)
Returns `true` if the given "object" is a `Date`. `false` otherwise.
@@ -115,7 +115,7 @@ Returns `true` if the given "object" is a `Date`. `false` otherwise.
// false
-### util.isError(object)
+## util.isError(object)
Returns `true` if the given "object" is an `Error`. `false` otherwise.
@@ -129,7 +129,7 @@ Returns `true` if the given "object" is an `Error`. `false` otherwise.
// false
-### util.pump(readableStream, writableStream, [callback])
+## util.pump(readableStream, writableStream, [callback])
Experimental
@@ -140,7 +140,7 @@ an error as its only argument and is called when `writableStream` is closed or
when an error occurs.
-### util.inherits(constructor, superConstructor)
+## util.inherits(constructor, superConstructor)
Inherit the prototype methods from one
[constructor](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor)
diff --git a/doc/api/vm.markdown b/doc/api/vm.markdown
index 3d3c168459..dfcf3506cd 100644
--- a/doc/api/vm.markdown
+++ b/doc/api/vm.markdown
@@ -1,4 +1,6 @@
-## Executing JavaScript
+# Executing JavaScript
+
+
You can access this module with:
@@ -7,7 +9,7 @@ You can access this module with:
JavaScript code can be compiled and run immediately or compiled, saved, and run later.
-### vm.runInThisContext(code, [filename])
+## vm.runInThisContext(code, [filename])
`vm.runInThisContext()` compiles `code`, runs it and returns the result. Running
code does not have access to local scope. `filename` is optional, it's used only
@@ -37,7 +39,7 @@ In case of syntax error in `code`, `vm.runInThisContext` emits the syntax error
and throws an exception.
-### vm.runInNewContext(code, [sandbox], [filename])
+## vm.runInNewContext(code, [sandbox], [filename])
`vm.runInNewContext` compiles `code`, then runs it in `sandbox` and returns the
result. Running code does not have access to local scope. The object `sandbox`
@@ -66,7 +68,7 @@ requires a separate process.
In case of syntax error in `code`, `vm.runInNewContext` emits the syntax error to stderr
and throws an exception.
-### vm.runInContext(code, context, [filename])
+## vm.runInContext(code, context, [filename])
`vm.runInContext` compiles `code`, then runs it in `context` and returns the
result. A (V8) context comprises a global object, together with a set of
@@ -100,14 +102,14 @@ requires a separate process.
In case of syntax error in `code`, `vm.runInContext` emits the syntax error to stderr
and throws an exception.
-### vm.createContext([initSandbox])
+## vm.createContext([initSandbox])
`vm.createContext` creates a new context which is suitable for use as the 2nd argument of a subsequent
call to `vm.runInContext`. A (V8) context comprises a global object together with a set of
build-in objects and functions. The optional argument `initSandbox` will be shallow-copied
to seed the initial contents of the global object used by the context.
-### vm.createScript(code, [filename])
+## vm.createScript(code, [filename])
`createScript` compiles `code` but does not run it. Instead, it returns a
`vm.Script` object representing this compiled code. This script can be run
@@ -119,6 +121,10 @@ In case of syntax error in `code`, `createScript` prints the syntax error to std
and throws an exception.
+## Class: Script
+
+A class for running scripts. Returned by vm.createScript.
+
### script.runInThisContext()
Similar to `vm.runInThisContext` but a method of a precompiled `Script` object.
diff --git a/doc/api/zlib.markdown b/doc/api/zlib.markdown
index 475723e88b..13af64dd97 100644
--- a/doc/api/zlib.markdown
+++ b/doc/api/zlib.markdown
@@ -1,4 +1,4 @@
-## Zlib
+# Zlib
You can access this module with:
@@ -8,7 +8,7 @@ This provides bindings to Gzip/Gunzip, Deflate/Inflate, and
DeflateRaw/InflateRaw classes. Each class takes the same options, and
is a readable/writable Stream.
-### Examples
+## Examples
Compressing or decompressing a file can be done by piping an
fs.ReadStream into a zlib stream, then into an fs.WriteStream.
@@ -101,109 +101,115 @@ tradeoffs involved in zlib usage.
}
}).listen(1337);
-### Constants
+## Constants
+
+
All of the constants defined in zlib.h are also defined on
`require('zlib')`. They are described in more detail in the zlib
documentation. See
for more details.
-### zlib.createGzip([options])
+## zlib.createGzip([options])
Returns a new [Gzip](#zlib.Gzip) object with an [options](#options).
-### zlib.createGunzip([options])
+## zlib.createGunzip([options])
Returns a new [Gunzip](#zlib.Gunzip) object with an [options](#options).
-### zlib.createDeflate([options])
+## zlib.createDeflate([options])
Returns a new [Deflate](#zlib.Deflate) object with an [options](#options).
-### zlib.createInflate([options])
+## zlib.createInflate([options])
Returns a new [Inflate](#zlib.Inflate) object with an [options](#options).
-### zlib.createDeflateRaw([options])
+## zlib.createDeflateRaw([options])
Returns a new [DeflateRaw](#zlib.DeflateRaw) object with an [options](#options).
-### zlib.createInflateRaw([options])
+## zlib.createInflateRaw([options])
Returns a new [InflateRaw](#zlib.InflateRaw) object with an [options](#options).
-### zlib.createUnzip([options])
+## zlib.createUnzip([options])
Returns a new [Unzip](#zlib.Unzip) object with an [options](#options).
-### zlib.Gzip
+## Class: zlib.Gzip
Compress data using gzip.
-### zlib.Gunzip
+## Class: zlib.Gunzip
Decompress a gzip stream.
-### zlib.Deflate
+## Class: zlib.Deflate
Compress data using deflate.
-### zlib.Inflate
+## Class: zlib.Inflate
Decompress a deflate stream.
-### zlib.DeflateRaw
+## Class: zlib.DeflateRaw
Compress data using deflate, and do not append a zlib header.
-### zlib.InflateRaw
+## Class: zlib.InflateRaw
Decompress a raw deflate stream.
-### zlib.Unzip
+## Class: zlib.Unzip
Decompress either a Gzip- or Deflate-compressed stream by auto-detecting
the header.
## Convenience Methods
+
+
All of these take a string or buffer as the first argument, and call the
supplied callback with `callback(error, result)`. The
compression/decompression engine is created using the default settings
in all convenience methods. To supply different options, use the
zlib classes directly.
-### zlib.deflate(buf, callback)
+## zlib.deflate(buf, callback)
Compress a string with Deflate.
-### zlib.deflateRaw(buf, callback)
+## zlib.deflateRaw(buf, callback)
Compress a string with DeflateRaw.
-### zlib.gzip(buf, callback)
+## zlib.gzip(buf, callback)
Compress a string with Gzip.
-### zlib.gunzip(buf, callback)
+## zlib.gunzip(buf, callback)
Decompress a raw Buffer with Gunzip.
-### zlib.inflate(buf, callback)
+## zlib.inflate(buf, callback)
Decompress a raw Buffer with Inflate.
-### zlib.inflateRaw(buf, callback)
+## zlib.inflateRaw(buf, callback)
Decompress a raw Buffer with InflateRaw.
-### zlib.unzip(buf, callback)
+## zlib.unzip(buf, callback)
Decompress a raw Buffer with Unzip.
## Options
+
+
Each class takes an options object. All options are optional. (The
convenience methods use the default settings for all options.)
@@ -219,7 +225,9 @@ relevant when compressing, and are ignored by the decompression classes.
See the description of `deflateInit2` and `inflateInit2` at
for more information on these.
-### Memory Usage Tuning
+## Memory Usage Tuning
+
+
From `zlib/zconf.h`, modified to node's usage:
diff --git a/doc/api_assets/anchor.png b/doc/api_assets/anchor.png
deleted file mode 100644
index 1ed163ee1a..0000000000
Binary files a/doc/api_assets/anchor.png and /dev/null differ
diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css
index 0ade5b2231..f67e9352e8 100644
--- a/doc/api_assets/style.css
+++ b/doc/api_assets/style.css
@@ -12,7 +12,7 @@ body {
border-top: 6px #8CC84B solid;
}
a {
- color: #690;
+ color: #480;
text-decoration: underline;
}
a:visited {
@@ -123,61 +123,61 @@ h1, h2, h3, h4, h5, h6 {
position: relative;
}
-h1 {
+header h1 {
font-family: Georgia, FreeSerif, Times, serif;
font-size: 30px;
font-weight: normal;
line-height: 36px;
- color: #690;
+ color: #480;
margin: 15px 0 11px;
}
-h2 {
+h1 {
font-size: 29px;
line-height: 33px;
margin: 2em 0 15px;
}
-#toc + h2 {
+#toc + h1 {
margin-top:1em;
padding-top:0;
}
-h3 {
+h2 {
font-size: 1.4em;
line-height: 1.0909em;
margin: 1.5em 0 0.5em;
}
-h3 + h3 {
+h2 + h2 {
margin: 0 0 0.5em;
}
-h4 {
+h3 {
font-size: 1.3em;
line-height: 1.1282em;
margin: 2.2em 0 0.5em;
}
-h4 + h4 {
+h3 + h3 {
margin: 0 0 0.5em;
}
- h3, h4 {
+ h2, h3 {
position:relative;
padding-right:40px;
}
- h2 span, h3 span, h4 span {
+ h1 span, h2 span, h3 span {
position:absolute;
display:block;
top:0;
right:0;
opacity: 0.3;
}
- h2 span:hover, h3 span:hover, h4 span:hover {
+ h1 span:hover, h2 span:hover, h3 span:hover {
opacity: 1;
}
- h2 span a, h3 span a, h4 span a {
+ h1 span a, h2 span a, h3 span a {
font-size: 0.8em;
color: #000;
text-decoration: none;
@@ -185,7 +185,7 @@ h4 + h4 {
font-weight:bold;
}
- h2 span a.top, h3 span a.top, h4 span a.top {
+ h1 span a.top, h3 span a.top, h3 span a.top {
/* XXX Get an image and clean up these two links
* so that they look nice next to one another.
* http://www.chrisglass.com/work/nodejs/website/v05/docs.html
@@ -210,7 +210,7 @@ h6 {
font-family: Monaco, Consolas, "Lucida Console", monospace;
margin: 0; padding: 0;
}
-
+
.pre {
font-family: Monaco, Consolas, "Lucida Console", monospace;
line-height: 1.5438em;
@@ -226,7 +226,7 @@ h6 {
margin: -0.5em 0 1.1em;
overflow-x:auto;
}
-
+
pre + h3 {
margin-top: 2.225em;
}
@@ -242,7 +242,7 @@ code.pre {
color: #d2d8ba;
/* preload platform-icons.png */
- background-image: url(platform-icons.png);
+ background-image: url(http://nodejs.org/images/platform-icons.png);
background-repeat: no-repeat;
background-position: -999em -999em;
}
@@ -271,22 +271,23 @@ hr {
line-height: 21px;
margin: 0 0 0.5em;
}
-
+
#toc h2 a {
float: right;
}
-
+
#toc hr {
margin: 1em 0 2em;
}
- #toc ul {
+ #toc ul, #api-section-index ul li, #api-section-index ul {
font-family: Georgia, FreeSerif, Times, serif;
+ color:#666!important;
}
#toc ul a {
text-decoration:none;
- border-bottom:1px dotted #690;
+ border-bottom:1px dotted #480;
}
#toc ul a:hover, #toc ul a:focus {
border-bottom:1px dotted #fff;
@@ -341,15 +342,15 @@ p tt, p code {
line-height: 23px;
}
-#column2.interior li a.home { background: url(icons-interior.png) no-repeat -156px 3px; }
-#column2.interior li a.download { background: url(icons-interior.png) no-repeat -156px -21px; }
-#column2.interior li a.about { background: url(icons-interior.png) no-repeat -156px -45px; }
-#column2.interior li a.npm { background: url(icons-interior.png) no-repeat -156px -69px; }
-#column2.interior li a.docs { background: url(icons-interior.png) no-repeat -156px -93px; }
-#column2.interior li a.blog { background: url(icons-interior.png) no-repeat -156px -117px; }
-#column2.interior li a.community { background: url(icons-interior.png) no-repeat -156px -141px; }
-#column2.interior li a.logos { background: url(icons-interior.png) no-repeat -156px -165px; }
-#column2.interior li a.jobs { background: url(icons-interior.png) no-repeat -156px -189px; }
+#column2.interior li a.home { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px 3px; }
+#column2.interior li a.download { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -21px; }
+#column2.interior li a.about { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -45px; }
+#column2.interior li a.npm { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -69px; }
+#column2.interior li a.docs { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -93px; }
+#column2.interior li a.blog { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -117px; }
+#column2.interior li a.community { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -141px; }
+#column2.interior li a.logos { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -165px; }
+#column2.interior li a.jobs { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -189px; }
#column2.interior li a.home.current { background-position: 2px 3px; }
#column2.interior li a.download.current { background-position: 2px -21px; }
@@ -381,7 +382,7 @@ p tt, p code {
}
#column2.interior p.twitter a {
- background: url(twitter-bird.png) no-repeat 0 4px;
+ background: url(http://nodejs.org/images/twitter-bird.png) no-repeat 0 4px;
padding-left: 37px;
text-decoration: none;
}
@@ -394,7 +395,7 @@ a.totop {
font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif;
font-weight: bold;
text-indent: -9999999px;
- background: url(anchor.png) no-repeat top left;
+ background: url(http://nodejs.org/images/anchor.png) no-repeat top left;
margin-right: 7px;
display: block;
width: 13px;
@@ -405,7 +406,7 @@ a.anchor {
font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif;
font-weight: bold;
text-indent: -9999999px;
- background: url(anchor.png) no-repeat top right;
+ background: url(http://nodejs.org/images/anchor.png) no-repeat top right;
display: block;
width: 13px;
border-bottom: 1px solid #cccccc;
@@ -427,19 +428,19 @@ a.anchor {
#footer a {
text-decoration:none;
border:none;
- color: #690;
+ color: #480;
}
#footer a:hover {
color:#000;
}
#footer p a {
- border-bottom:1px dotted #690;
+ border-bottom:1px dotted #480;
color: #878b78;
}
#footer ul {
- background: url(footer-logo-alt.png) left 17px no-repeat;
+ background: url(http://nodejs.org/images/footer-logo-alt.png) left 17px no-repeat;
padding: 23px 0 0 195px;
height: 26px;
margin-left: -1px;
@@ -473,7 +474,7 @@ a.anchor {
}
#footer ul li a.twitter {
- background: url(twitter-bird.png) no-repeat 5px 0px;
+ background: url(http://nodejs.org/images/twitter-bird.png) no-repeat 5px 0px;
padding-left: 25px;
}
diff --git a/doc/community/index.html b/doc/community/index.html
index 65c687b87b..038996d7f6 100644
--- a/doc/community/index.html
+++ b/doc/community/index.html
@@ -23,7 +23,7 @@
@@ -163,7 +163,7 @@
+ src="http://nodejs.org/images/not-invented-here.png" width="100%">
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
