Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

documentation refactor

wip: Makefile changes

Refactor cluster.markdown

Add return value

wip: Getting closer

Title should be uppercase

Promoting a lot of headings, update style correspondingly

Parsing module pages properly now

Better tokens for version, toc, etc.

Build html from markdown, not from json

Much closer.  Better coverage.  Generating html now.

This file is going away, but clean it up for now anyway

API doc refactor, part 1, addons through crypto

Absolute depth change is ok.

It's only depth *increase* of greater than 1 that's bad.

Volatility -> Stability ratings

Refactor buffers.markdown

Document 'silent' option to fork

refactor debugger.markdown

Refactor doc/api/dgram.markdown

apidocs: generate html and json efficiently

Closer to final format

'make doc' passing.  Still needs more cleanup

docs: Remove extraneous heading from toc

Remove undocumented sections

doc: 'examples' sections are assumed type=misc

Only add id counter when necessary

doc: Move children of 'misc' sections to the grandparent

doc: support @include lines for TOC/index

doc: TOC bullet/link contrast fixes

Refactor module documentation

Recognize top-level methods

Process signatures, even without a ul

s/child_processes/child_process/

Remove empty appendix

Add 'about these docs' section

Don't copy miscs up to the parent (results in cycles)

cleanup example markdown

Mention creation of documentation, as well
  • Loading branch information...
commit 22a2975e64a61df7955523452befd54beef7514d 1 parent 90fd70d
@isaacs authored
Showing with 3,106 additions and 617 deletions.
  1. +8 −4 Makefile
  2. +1 −1  doc/about/index.html
  3. +2 −4 doc/api/_toc.markdown
  4. +9 −9 doc/api/addons.markdown
  5. +2 −6 doc/api/all.markdown
  6. +1 −1  doc/api/appendix_1.markdown
  7. 0  doc/api/appendix_2.markdown
  8. +12 −12 doc/api/assert.markdown
  9. +177 −51 doc/api/buffers.markdown
  10. +137 −36 doc/api/{child_processes.markdown → child_process.markdown}
  11. +120 −54 doc/api/cluster.markdown
  12. +57 −16 doc/api/crypto.markdown
  13. +11 −11 doc/api/debugger.markdown
  14. +53 −21 doc/api/dgram.markdown
  15. +11 −11 doc/api/dns.markdown
  16. +59 −0 doc/api/documentation.markdown
  17. +13 −12 doc/api/events.markdown
  18. +93 −90 doc/api/fs.markdown
  19. +54 −15 doc/api/globals.markdown
  20. +18 −17 doc/api/http.markdown
  21. +3 −3 doc/api/https.markdown
  22. +93 −12 doc/api/modules.markdown
  23. +49 −56 doc/api/net.markdown
  24. +14 −12 doc/api/os.markdown
  25. +8 −8 doc/api/path.markdown
  26. +35 −30 doc/api/process.markdown
  27. +7 −5 doc/api/querystring.markdown
  28. +7 −4 doc/api/readline.markdown
  29. +5 −3 doc/api/repl.markdown
  30. +14 −10 doc/api/stdio.markdown
  31. +5 −1 doc/api/streams.markdown
  32. +3 −1 doc/api/synopsis.markdown
  33. +8 −5 doc/api/timers.markdown
  34. +17 −9 doc/api/tls.markdown
  35. +5 −5 doc/api/tty.markdown
  36. +4 −4 doc/api/url.markdown
  37. +11 −11 doc/api/util.markdown
  38. +12 −6 doc/api/vm.markdown
  39. +33 −25 doc/api/zlib.markdown
  40. +23 −22 doc/api_assets/style.css
  41. +20 −14 doc/template.html
  42. +96 −0 tools/doc/README.md
  43. +99 −0 tools/doc/generate.js
  44. +154 −0 tools/doc/html.js
  45. +530 −0 tools/doc/json.js
  46. +1 −0  tools/doc/node_modules/.bin/marked
  47. +2 −0  tools/doc/node_modules/marked/.npmignore
  48. +19 −0 tools/doc/node_modules/marked/LICENSE
  49. +9 −0 tools/doc/node_modules/marked/Makefile
  50. +135 −0 tools/doc/node_modules/marked/README.md
  51. +115 −0 tools/doc/node_modules/marked/bin/marked
  52. +1 −0  tools/doc/node_modules/marked/index.js
  53. +662 −0 tools/doc/node_modules/marked/lib/marked.js
  54. +39 −0 tools/doc/node_modules/marked/man/marked.1
  55. +15 −0 tools/doc/node_modules/marked/package.json
  56. +15 −0 tools/doc/package.json
View
12 Makefile
@@ -92,7 +92,8 @@ test-npm-publish: node
npm_package_config_publishtest=true ./node deps/npm/test/run.js
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 out/doc/images
@@ -115,7 +116,7 @@ website_files = \
out/doc/logos/index.html \
$(doc_images)
-doc: node $(apidoc_dirs) $(website_files) $(apiassets) $(apidocs)
+doc: node $(apidoc_dirs) $(website_files) $(apiassets) $(apidocs) tools/doc/
$(apidoc_dirs):
mkdir -p $@
@@ -126,8 +127,11 @@ out/doc/api/assets/%: doc/api_assets/% out/doc/api/assets/
out/doc/%: doc/%
cp -r $< $@
-out/doc/api/%.html: doc/api/%.markdown node $(apidoc_dirs) $(apiassets) tools/doctool/doctool.js
- out/Release/node tools/doctool/doctool.js doc/template.html $< > $@
+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 tools/doc/generate.js --format=html --template=doc/template.html $< > $@
website-upload: doc
rsync -r out/doc/ node@nodejs.org:~/web/nodejs.org/
View
2  doc/about/index.html
@@ -102,7 +102,7 @@
<p>But what about multiple-processor concurrency? Aren't
threads necessary to scale programs to multi-core computers?
You can start new processes via <code><a
- href="http://nodejs.org/docs/latest/api/child_processes.html#child_process.fork">child_process.fork()</a></code>
+ href="http://nodejs.org/docs/latest/api/child_process.html#child_process.fork">child_process.fork()</a></code>
these other processes will be scheduled in parallel. For load
balancing incoming connections across multiple processes use
<a href="http://nodejs.org/docs/latest/api/cluster.html">the
View
6 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)
@@ -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)
View
18 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.
View
8 doc/api/all.markdown
@@ -1,3 +1,4 @@
+@include documentation
@include synopsis
@include globals
@include stdio
@@ -5,9 +6,7 @@
@include modules
@include addons
@include process
-@include constants
@include util
-@include freelist
@include events
@include buffers
@include streams
@@ -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
View
2  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
View
0  doc/api/appendix_2.markdown
No changes.
View
24 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.
View
228 doc/api/buffers.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]
+
+<!--type=property-->
+<!--name=[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 03 04 23 42>
-### 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 de ad be ef>
// <Buffer ad de ef be>
-### 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 fe ed fa ce>
// <Buffer ce fa ed fe>
-### 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 4f 4a fe bb>
// <Buffer bb fe 4a 4f>
-### 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 43 eb d5 b7 dd f9 5f d7>
// <Buffer d7 5f f9 dd b7 d5 eb 43>
-### 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.
View
173 doc/api/child_processes.markdown → 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
@@ -33,19 +44,36 @@ An alternative way to check if you can send messages is to see if the
### 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:
@@ -56,8 +84,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.
@@ -150,17 +218,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.
@@ -182,7 +267,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,
@@ -198,14 +284,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
@@ -278,22 +398,3 @@ there is no IPC channel keeping it alive. When calling this method the
`connected` flag will be set to `false`. Please note that you can also call
`process.disconnect()` in the child process.
-### 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)`
View
174 doc/api/cluster.markdown
@@ -1,4 +1,6 @@
-## Cluster
+# Cluster
+
+ Stability: 1 - Experimental
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
@@ -36,19 +38,40 @@ Running node will now share port 8000 between the workers:
Worker 2437 online
-### cluster.isMaster
+This feature was introduced recently, and may change in future versions.
+Please try it out and provide feedback.
+
+## cluster.settings
+
+* {Object}
+ * `exec` {String} file path to worker file. (Default=`__filename`)
+ * `args` {Array} string arguments passed to worker.
+ (Default=`process.argv.slice(2)`)
+ * `silent` {Boolean} whether or not to send output to parent's stdio.
+ (Default=`false`)
+
+All settings set by the `.setupMaster` is stored in this settings object.
+This object is not supposed to be change or set manually, by you.
+
+## cluster.isMaster
+
+* {Boolean}
-This boolean flag is true if the process is a master. This is determined
+True if the process is a master. This is determined
by the `process.env.NODE_UNIQUE_ID`. If `process.env.NODE_UNIQUE_ID` is
-undefined `isMaster` is `true`.
+undefined, then `isMaster` is `true`.
-### cluster.isWorker
+## cluster.isWorker
+
+* {Boolean}
This boolean flag is true if the process is a worker forked from a master.
-If the `process.env.NODE_UNIQUE_ID` is set to a value different efined
+If the `process.env.NODE_UNIQUE_ID` is set to a value, then
`isWorker` is `true`.
-### Event: 'fork'
+## Event: 'fork'
+
+* `worker` {Worker object}
When a new worker is forked the cluster module will emit a 'fork' event.
This can be used to log worker activity, and create you own timeout.
@@ -69,19 +92,23 @@ This can be used to log worker activity, and create you own timeout.
errorMsg();
});
-### Event: 'online'
+## Event: 'online'
+
+* `worker` {Worker object}
After forking a new worker, the worker should respond with a online message.
When the master receives a online message it will emit such event.
The difference between 'fork' and 'online' is that fork is emitted when the
-master tries to fork a worker, and 'online' is emitted when the worker is being
-executed.
+master tries to fork a worker, and 'online' is emitted when the worker is
+being executed.
cluster.on('online', function (worker) {
console.log("Yay, the worker responded after it was forked");
});
-### Event: 'listening'
+## Event: 'listening'
+
+* `worker` {Worker object}
When calling `listen()` from a worker, a 'listening' event is automatically assigned
to the server instance. When the server is listening a message is send to the master
@@ -91,7 +118,9 @@ where the 'listening' event is emitted.
console.log("We are now connected");
});
-### Event: 'death'
+## Event: 'death'
+
+* `worker` {Worker object}
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.
@@ -101,15 +130,25 @@ This can be used to restart the worker by calling `fork()` again.
cluster.fork();
});
-### Event 'setup'
+## Event: 'setup'
+
+* `worker` {Worker object}
-When the `.setupMaster()` function has been executed this event emits. If `.setupMaster()`
-was not executed before `fork()` this function will call `.setupMaster()` with no arguments.
+When the `.setupMaster()` function has been executed this event emits.
+If `.setupMaster()` was not executed before `fork()` this function will
+call `.setupMaster()` with no arguments.
-### cluster.setupMaster([options])
+## cluster.setupMaster([settings])
-The `setupMaster` is used to change the default 'fork' behavior. It takes one option
-object argument.
+* `settings` {Object}
+ * `exec` {String} file path to worker file. (Default=`__filename`)
+ * `args` {Array} string arguments passed to worker.
+ (Default=`process.argv.slice(2)`)
+ * `silent` {Boolean} whether or not to send output to parent's stdio.
+ (Default=`false`)
+
+The `setupMaster` is used to change the default 'fork' behavior. It takes
+one option object argument.
Example:
@@ -121,26 +160,28 @@ Example:
});
cluster.autoFork();
-The options argument can contain 3 different properties.
+## cluster.fork([env])
-- `exec` are the file path to the worker file, by default this is the same file as the master.
-- `args` are a array of arguments send along with the worker, by default this is `process.argv.slice(2)`.
-- `silent`, if this option is true the output of a worker won't propagate to the master, by default this is false.
+* `env` {Object} Key/value pairs to add to child process environment.
+* return {Worker object}
-### cluster.settings
+Spawn a new worker process. This can only be called from the master process.
-All settings set by the `.setupMaster` is stored in this settings object.
-This object is not supposed to be change or set manually, by you.
+## cluster.settings
-All propertys are `undefined` if they are not yet set.
+* {Object}
+ * `exec` {String} file path to worker file. Default: `__filename`
+ * `args` {Array} string arguments passed to worker.
+ (Default=`process.argv.slice(2)`)
+ * `silent` {Boolean} whether or not to send output to parent's stdio.
+ (Default=`false`)
-### cluster.fork([env])
+All settings set by the `.setupMaster` is stored in this settings object.
+This object is not supposed to be change or set manually.
-Spawn a new worker process. This can only be called from the master process.
-The function takes an optional `env` object. The properties in this object
-will be added to the process environment in the worker.
+## cluster.workers
-### cluster.workers
+* {Object}
In the cluster all living worker objects are stored in this object by there
`uniqueID` as the key. This makes it easy to loop through all living workers.
@@ -162,27 +203,48 @@ the worker's uniqueID is the easiest way to find the worker.
var worker = cluster.workers[uniqueID];
});
-## Worker
+## Class: Worker
-This object contains all public information and method about a worker.
+A Worker object contains all public information and method about a worker.
In the master it can be obtained using `cluster.workers`. In a worker
it can be obtained using `cluster.worker`.
-### Worker.uniqueID
+### worker.uniqueID
+
+* {String}
+
+Each new worker is given its own unique id, this id is stored in the
+`uniqueID`.
+
+While a worker is alive, this is the key that indexes it in
+cluster.workers
+
+### worker.process
+
+* {ChildProcess object}
+
+All workers are created using `child_process.fork()`, the returned object
+from this function is stored in process.
-Each new worker is given its own unique id, this id is stored in the `uniqueID`.
+See: [Child Process module](child_process.html)
-### Worker.process
+### worker.suicide
-All workers are created using `child_process.fork()`, the returned object from this
-function is stored in process.
+* {Boolean}
-### Worker.send(message, [sendHandle])
+This property is a boolean. It is set when a worker dies, until then it is
+`undefined`. It is true if the worker was killed using the `.destroy()`
+method, and false otherwise.
-This function is equal to the send methods provided by `child_process.fork()`.
-In the master you should use this function to send a message to a specific worker.
-However in a worker you can also use `process.send(message)`, since this is the same
-function.
+### worker.send(message, [sendHandle])
+
+* `message` {Object}
+* `sendHandle` {Handle object}
+
+This function is equal to the send methods provided by
+`child_process.fork()`. In the master you should use this function to
+send a message to a specific worker. However in a worker you can also use
+`process.send(message)`, since this is the same function.
This example will echo back all messages from the master:
@@ -196,10 +258,11 @@ This example will echo back all messages from the master:
});
}
-### Worker.destroy()
+### worker.destroy()
-This function will kill the worker, and inform the master to not spawn a new worker.
-To know the difference between suicide and accidentally death a suicide boolean is set to true.
+This function will kill the worker, and inform the master to not spawn a
+new worker. To know the difference between suicide and accidentally death
+a suicide boolean is set to true.
cluster.on('death', function (worker) {
if (worker.suicide === true) {
@@ -210,12 +273,9 @@ To know the difference between suicide and accidentally death a suicide boolean
// destroy worker
worker.destroy();
-### Worker.suicide
-
-This property is a boolean. It is set when a worker dies, until then it is `undefined`.
-It is true if the worker was killed using the `.destroy()` method, and false otherwise.
+### Event: 'message'
-### Event: message
+* `message` {Object}
This event is the same as the one provided by `child_process.fork()`.
In the master you should use this event, however in a worker you can also use
@@ -260,7 +320,9 @@ in the master process using the message system:
}).listen(8000);
}
-### Event: online
+### Event: 'online'
+
+* `worker` {Worker object}
Same as the `cluster.on('online')` event, but emits only when the state change
on the specified worker.
@@ -269,7 +331,9 @@ on the specified worker.
// Worker is online
};
-### Event: listening
+### Event: 'listening'
+
+* `worker` {Worker object}
Same as the `cluster.on('listening')` event, but emits only when the state change
on the specified worker.
@@ -278,7 +342,9 @@ on the specified worker.
// Worker is listening
};
-### Event: death
+### Event: 'death'
+
+* `worker` {Worker object}
Same as the `cluster.on('death')` event, but emits only when the state change
on the specified worker.
View
73 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
<http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
-### 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.
@@ -97,7 +109,7 @@ 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).
-### crypto.createCipheriv(algorithm, key, iv)
+## crypto.createCipheriv(algorithm, key, iv)
Creates and returns a cipher object, with the given algorithm, key and iv.
@@ -105,6 +117,12 @@ Creates and returns a cipher object, with the given algorithm, key and iv.
algorithm. `iv` is an Initialization vector. `key` and `iv` must be `'binary'`
encoded string (See the [Buffers](buffers.html) for more information).
+## Class: Cipher
+
+Class for encrypting data.
+
+Returned by `crypto.createCipher` and `crypto.createCipheriv`.
+
### cipher.update(data, [input_encoding], [output_encoding])
Updates the cipher with `data`, the encoding of which is given in
@@ -130,16 +148,22 @@ the length of the entire input data must be a multiple of the cipher's block siz
Useful for non-standard padding, e.g. using `0x0` instead of PKCS padding. You must call this before `cipher.final`.
-### 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'`
@@ -163,12 +187,18 @@ You can disable auto padding if the data has been encrypted without standard blo
ciphers block size. You must call this before streaming data to `decipher.update`.
-### 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.
@@ -184,12 +214,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.
@@ -207,17 +242,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
@@ -264,7 +305,7 @@ or `'base64'`. Defaults to `'binary'`.
Sets the Diffie-Hellman private key. Key encoding can be `'binary'`, `'hex'`,
or `'base64'`. Defaults to `'binary'`.
-### crypto.getDiffieHellman(group_name)
+## crypto.getDiffieHellman(group_name)
Creates a predefined Diffie-Hellman key exchange object.
The supported groups are: `'modp1'`, `'modp2'`, `'modp5'`
@@ -294,13 +335,13 @@ Example (obtaining a shared secret):
/* alice_secret and bob_secret should be the same */
console.log(alice_secret == bob_secret);
-### 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:
View
22 doc/api/debugger.markdown
@@ -1,4 +1,6 @@
-## Debugger
+# Debugger
+
+<!-- type=concept -->
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,9 +87,9 @@ 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
@@ -95,7 +97,7 @@ prints the active watchers. To remove a watcher, type
* `out`, `o` - Step out
* `pause` - Pause running code (like pause button in Developer TOols)
-#### Breakpoints
+### Breakpoints
* `setBreakpoint()`, `sb()` - Set breakpoint on current line
* `setBreakpoint(line)`, `sb(line)` - Set breakpoint on specific line
@@ -105,7 +107,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
@@ -116,21 +118,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`.
-
-
View
74 doc/api/dgram.markdown
@@ -1,50 +1,65 @@
-## UDP / Datagram Sockets
+# UDP / Datagram Sockets
+
+<!-- name=dgram -->
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
View
22 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
View
59 doc/api/documentation.markdown
@@ -0,0 +1,59 @@
+# About this Documentation
+
+<!-- type=misc -->
+
+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
+
+<!--type=misc-->
+
+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.
View
25 doc/api/events.markdown
@@ -1,4 +1,4 @@
-## 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 +12,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 +24,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 +33,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 +43,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 +56,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 +69,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 +79,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.
View
183 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.