From 178e2ce65fe4609a3f4c9a22d569b6d080bd5134 Mon Sep 17 00:00:00 2001
From: Fedor Indutny <fedor.indutny@gmail.com>
Date: Wed, 12 Oct 2011 02:14:00 +0700
Subject: [PATCH] docs: improve addons, readline, repl documentation

---
 doc/api/addons.markdown   | 32 +++++++++++++++-----------------
 doc/api/readline.markdown |  8 +++++++-
 doc/api/repl.markdown     | 10 ++++++++--
 3 files changed, 30 insertions(+), 20 deletions(-)

diff --git a/doc/api/addons.markdown b/doc/api/addons.markdown
index 5d8edd02d7..6b54069f2d 100644
--- a/doc/api/addons.markdown
+++ b/doc/api/addons.markdown
@@ -8,16 +8,10 @@ knowledge of several libraries:
    creating objects, calling functions, etc.  Documented mostly in the
    `v8.h` header file (`deps/v8/include/v8.h` in the Node source tree).
 
- - libev, C event loop library. Anytime one needs to wait for a file
-   descriptor to become readable, wait for a timer, or wait for a signal to
-   received one will need to interface with libev.  That is, if you perform
-   any I/O, libev will need to be used.  Node uses the `EV_DEFAULT` event
-   loop.  Documentation can be found [here](http://cvs.schmorp.de/libev/ev.html).
-
- - libeio, C thread pool library. Used to execute blocking POSIX system
-   calls asynchronously. Mostly wrappers already exist for such calls, in
-   `src/file.cc` so you will probably not need to use it. If you do need it,
-   look at the header file `deps/libeio/eio.h`.
+ - [libuv](https://github.com/joyent/libuv), C event loop library. Anytime one
+   needs to wait for a file descriptor to become readable, wait for a timer, or
+   wait for a signal to received one will need to interface with libuv. That is,
+   if you perform any I/O, libuv will need to be used.
 
  - Internal Node libraries. Most importantly is the `node::ObjectWrap`
    class which you will likely want to derive from.
@@ -31,7 +25,7 @@ libraries.
 To get started let's make a small Addon which does the following except in
 C++:
 
-    exports.hello = 'world';
+    exports.hello = function() { return 'world'; };
 
 To get started we create a file `hello.cc`:
 
@@ -39,12 +33,15 @@ To get started we create a file `hello.cc`:
 
     using namespace v8;
 
-    extern "C" void
-    init (Handle<Object> target)
-    {
+    Handle<Value> Method(const Arguments &args) {
       HandleScope scope;
-      target->Set(String::New("hello"), String::New("world"));
+      return String::New("world");
+    }
+
+    void init (Handle<Object> target) {
+      NODE_SET_METHOD(target, Method);
     }
+    NODE_MODULE(hello, init)
 
 This source code needs to be built into `hello.node`, the binary Addon. To
 do this we create a file called `wscript` which is python code and looks
@@ -72,9 +69,10 @@ Running `node-waf configure build` will create a file
 `node-waf` is just [WAF](http://code.google.com/p/waf), the python-based build system. `node-waf` is
 provided for the ease of users.
 
-All Node addons must export a function called `init` with this signature:
+All Node addons must export an initialization function:
 
-    extern 'C' void init (Handle<Object> target)
+    void Initialize (Handle<Object> target);
+    NODE_MODULE(hello, Initialize)
 
 For the moment, that is all the documentation on addons. Please see
 <https://github.com/ry/node_postgres> for a real example.
diff --git a/doc/api/readline.markdown b/doc/api/readline.markdown
index 81975be6dc..a161001bf1 100644
--- a/doc/api/readline.markdown
+++ b/doc/api/readline.markdown
@@ -26,6 +26,12 @@ Takes two streams and creates a readline interface. The `completer` function
 is used for autocompletion. When given a substring, it returns `[[substr1,
 substr2, ...], originalsubstring]`.
 
+Also `completer` can be run in async mode if it accepts two arguments:
+
+  function completer(linePartial, callback) {
+    callback(null, [['123'], linePartial]);
+  }
+
 `createInterface` is commonly used with `process.stdin` and
 `process.stdout` in order to accept user input:
 
@@ -130,4 +136,4 @@ line interface:
 Take a look at this slightly more complicated
 [example](https://gist.github.com/901104), and
 [http-console](http://github.com/cloudhead/http-console) for a real-life use
-case.
\ No newline at end of file
+case.
diff --git a/doc/api/repl.markdown b/doc/api/repl.markdown
index fe2c8b7c82..c0b9789e1b 100644
--- a/doc/api/repl.markdown
+++ b/doc/api/repl.markdown
@@ -27,11 +27,17 @@ For example, you could add this to your bashrc file:
     alias node="env NODE_NO_READLINE=1 rlwrap node"
 
 
-### repl.start(prompt='> ', stream=process.stdin)
+### repl.start(prompt='> ', stream=process.stdin, eval=eval)
 
 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
-`process.stdin`.
+`process.stdin`. `eval` is optional too and defaults to async wrapper for `eval`.
+
+You can use your own `eval` function if it has following signature:
+
+    function eval(cmd, callback) {
+      callback(null, result);
+    }
 
 Multiple REPLs may be started against the same running instance of node.  Each
 will share the same global object but will have unique I/O.