Write new documentation

Makefile

@@ -83,6 +83,13 @@ forcetest:
 	cd test/ && node-gyp rebuild && cd ..
 	npm test
 
+docs: README.md doc/.build.sh doc/asyncworker.md doc/buffers.md doc/callback.md \
+		doc/converters.md doc/errors.md doc/maybe_types.md doc/methods.md doc/new.md \
+		doc/node_misc.md doc/persistent.md doc/scopes.md doc/script.md doc/string_bytes.md \
+		doc/v8_internals.md doc/v8_misc.md
+	doc/.build.sh
+
+
 $(ADDONS): nan.h nan_new.h nan_implementation_pre_12_inl.h nan_implementation_12_inl.h \
 		nan_callbacks.h nan_callbacks_12_inl.h nan_callbacks_pre_12_inl.h \
 		nan_converters.h nan_converters_43_inl.h nan_converters_pre_43_inl.h \

doc/.build.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+
+files="           \
+  methods.md      \
+  scopes.md       \
+  persistent.md   \
+  new.md          \
+  converters.md   \
+  maybe_types.md  \
+  script.md       \
+  errors.md       \
+  buffers.md      \
+  callback.md     \
+  asyncworker.md  \
+  string_bytes.md \
+  v8_internals.md \
+  v8_misc.md      \
+  node_misc.md    \
+"
+
+__dirname=$(dirname "${BASH_SOURCE[0]}")
+head=$(perl -e 'while (<>) { if (!$en){print;} if ($_=~/<!-- START/){$en=1} };' $__dirname/../README.md)
+tail=$(perl -e 'while (<>) { if ($_=~/<!-- END/){$st=1} if ($st){print;} };' $__dirname/../README.md)
+apidocs=$(for f in $files; do
+  perl -pe '
+    last if /^<a name/;
+    $_ =~ s/^## /### /;
+    $_ =~ s/<a href="#/<a href="doc\/'$f'#/;
+  ' $__dirname/$f;
+done)
+
+cat > $__dirname/../README.md << EOF
+$head
+
+$apidocs
+
+$tail
+EOF

doc/asyncworker.md

@@ -0,0 +1,97 @@
+## Asynchronous work helpers
+
+`Nan::AsyncWorker` and `Nan::AsyncProgressWorker` are helper classes that make working with asynchronous code easier.
+
+ - <a href="#api_nan_async_worker"><b><code>Nan::AsyncWorker</code></b></a>
+ - <a href="#api_nan_async_progress_worker"><b><code>Nan::AsyncProgressWorker</code></b></a>
+ - <a href="#api_nan_async_queue_worker"><b><code>Nan::AsyncQueueWorker</code></b></a>
+
+<a name="api_nan_async_worker"></a>
+### Nan::AsyncWorker
+
+`Nan::AsyncWorker` is an _abstract_ class that you can subclass to have much of the annoying asynchronous queuing and handling taken care of for you. It can even store arbitrary V8 objects for you and have them persist while the asynchronous work is in progress.
+
+Definition:
+
+```c++
+class AsyncWorker {
+ public:
+  explicit AsyncWorker(Callback *callback_);
+
+  virtual ~AsyncWorker();
+
+  virtual void WorkComplete();
+
+  void SaveToPersistent(const char *key, const v8::Local<v8::Value> &value);
+
+  void SaveToPersistent(const v8::Handle<v8::String> &key,
+                        const v8::Local<v8::Value> &value);
+
+  void SaveToPersistent(uint32_t index,
+                        const v8::Local<v8::Value> &value);
+
+  v8::Local<v8::Value> GetFromPersistent(const char *key) const;
+
+  v8::Local<v8::Value> GetFromPersistent(const v8::Local<v8::String> &key) const;
+
+  v8::Local<v8::Value> GetFromPersistent(uint32_t index) const;
+
+  virtual void Execute() = 0;
+
+  uv_work_t request;
+
+  virtual void Destroy();
+
+ protected:
+  Persistent<v8::Object> persistentHandle;
+
+  Callback *callback;
+
+  virtual void HandleOKCallback();
+
+  virtual void HandleErrorCallback();
+
+  void SetErrorMessage(const char *msg);
+
+  const char* ErrorMessage();
+};
+```
+
+<a name="api_nan_async_progress_worker"></a>
+### Nan::AsyncProgressWorker
+
+`Nan::AsyncProgressWorker` is an _abstract_ class that extends `Nan::AsyncWorker` and adds additional progress reporting callbacks that can be used during the asynchronous work execution to provide progress data back to JavaScript.
+
+Definition:
+
+```c++
+class AsyncProgressWorker : public AsyncWorker {
+ public:
+  explicit AsyncProgressWorker(Callback *callback_);
+
+  virtual ~AsyncProgressWorker();
+
+  void WorkProgress();
+
+  class ExecutionProgress {
+   public:
+    void Send(const char* data, size_t size) const;
+  };
+
+  virtual void Execute(const ExecutionProgress& progress) = 0;
+
+  virtual void HandleProgressCallback(const char *data, size_t size) = 0;
+
+  virtual void Destroy();
+```
+
+<a name="api_nan_async_queue_worker"></a>
+### Nan::AsyncQueueWorker
+
+`Nan::AsyncQueueWorker` will run a `Nan::AsyncWorker` asynchronously via libuv. Both the `execute` and `after_work` steps are taken care of for you. Most of the logic for this is embedded in `Nan::AsyncWorker`.
+
+Definition:
+
+```c++
+void AsyncQueueWorker(AsyncWorker *);
+```

doc/buffers.md

@@ -0,0 +1,40 @@
+## Buffers
+
+NAN's `node::Buffer` helpers exist as the API has changed across supported Node versions. Use these methods to ensure compatibility.
+
+ - <a href="#api_nan_new_buffer"><b><code>Nan::NewBuffer()</code></b></a>
+ - <a href="#api_nan_copy_buffer"><b><code>Nan::CopyBuffer()</code></b></a>
+
+
+<a name="api_nan_new_buffer"></a>
+### Nan::NewBuffer()
+
+Allocate a new `node::Buffer` object with the specified size and optional data. Calls `node::Buffer::New()`.
+
+Note that when creating a `Buffer` using `Nan::NewBuffer()` and an existing `char*`, it is assumed that the ownership of the pointer is being transferred to the new `Buffer` for management. You _must not_ free the memory space manually once you have created a `Buffer` in this way.
+
+Signature:
+
+```c++
+Nan::MaybeLocal<v8::Object> Nan::NewBuffer(uint32_t size)
+Nan::MaybeLocal<v8::Object> Nan::NewBuffer(char* data, uint32_t size)
+// uses `node::smalloc::FreeCallback` on older versions of Node
+Nan::MaybeLocal<v8::Object> Nan::NewBuffer(char *data,
+                                           size_t length,
+                                           node::Buffer::FreeCallback callback,
+                                           void *hint)
+```
+
+
+<a name="api_nan_copy_buffer"></a>
+### Nan::CopyBuffer()
+
+Similar to [`Nan::NewBuffer()`](#api_nan_new_buffer) except that an implicit memcpy will occur within Node. Calls `node::Buffer::Copy()`.
+
+Management of the `char*` is left to the user, you should manually free the memory space if necessary as the new `Buffer` will have its own copy.
+
+Signature:
+
+```c++
+Nan::MaybeLocal<v8::Object> Nan::CopyBuffer(const char *data, uint32_t size)
+```

doc/callback.md

@@ -0,0 +1,52 @@
+## Nan::Callback
+
+`Nan::Callback` makes it easier to use `v8::Function` handles as callbacks. A class that wraps a `v8::Function` handle, protecting it from garbage collection and making it particularly useful for storage and use across asynchronous execution.
+
+ - <a href="#api_nan_callback"><b><code>Nan::Callback</code></b></a>
+
+<a name="api_nan_callback"></a>
+### Nan::Callback
+
+```c++
+class Callback {
+ public:
+  Callback();
+
+  explicit Callback(const v8::Handle<v8::Function> &fn);
+
+  ~Callback();
+
+  bool operator==(const Callback &other) const;
+
+  bool operator!=(const Callback &other) const;
+
+  v8::Local<v8::Function> operator*() const;
+
+  v8::Local<v8::Value> operator()(v8::Handle<v8::Object> target,
+                                  int argc = 0,
+                                  v8::Handle<v8::Value> argv[] = 0) const;
+
+  v8::Local<v8::Value> operator()(int argc = 0,
+                                  v8::Handle<v8::Value> argv[] = 0) const;
+
+  void SetFunction(const v8::Handle<v8::Function> &fn);
+
+  v8::Local<v8::Function> GetFunction() const;
+
+  bool IsEmpty() const;
+
+  v8::Local<v8::Value> Call(v8::Handle<v8::Object> target,
+                            int argc,
+                            v8::Handle<v8::Value> argv[]) const;
+
+  v8::Local<v8::Value> Call(int argc, v8::Handle<v8::Value> argv[]) const;
+};
+```
+
+Example usage:
+
+```c++
+v8::Local<v8::Function> function;
+Nan::Callback callback(function);
+callback->Call(0, 0);
+```

doc/converters.md

@@ -0,0 +1,41 @@
+## Converters
+
+NAN contains functions that convert `v8::Value`s to other `v8::Value` types and native types. Since type conversion is not guaranteed to succeed, they return `Nan::Maybe` types. These converters can be used in place of `value->ToX()` and `value->XValue()` (where `X` is one of the types, e.g. `Boolean`) in a way that provides a consistent interface across V8 versions. Newer versions of V8 use the new `v8::Maybe` and `v8::MaybeLocal` types for these conversions, older versions don't have this functionality so it is provided by NAN.
+
+ - <a href="#api_nan_to"><b><code>Nan::To</code></b></a>
+
+<a name="api_nan_to"></a>
+### Nan::To
+
+Converts a `v8::Local<v8::Value>` to a different subtype of `v8::Value` or to a native data type. Returns a `Nan::MaybeLocal<>` or a `Nan::Maybe<>` accordingly.
+
+See [maybe_types.md](./maybe_types.md) for more information on `Nan::Maybe` types.
+
+Signatures:
+
+```c++
+// V8 types
+Nan::MaybeLocal<v8::Boolean> Nan::To<v8::Boolean>(v8::Local<v8::Value> val);
+Nan::MaybeLocal<v8::Int32> Nan::To<v8::Int32>(v8::Local<v8::Value> val);
+Nan::MaybeLocal<v8::Integer> Nan::To<v8::Integer>(v8::Local<v8::Value> val);
+Nan::MaybeLocal<v8::Object> Nan::To<v8::Object>(v8::Local<v8::Value> val);
+Nan::MaybeLocal<v8::Number> Nan::To<v8::Number>(v8::Local<v8::Value> val);
+Nan::MaybeLocal<v8::String> Nan::To<v8::String>(v8::Local<v8::Value> val);
+Nan::MaybeLocal<v8::Uint32> Nan::To<v8::Uint32>(v8::Local<v8::Value> val);
+
+// Native types
+Nan::Maybe<bool> Nan::To<bool>(v8::Local<v8::Value> val);
+Nan::Maybe<double> Nan::To<double>(v8::Local<v8::Value> val);
+Nan::Maybe<int32_t> Nan::To<int32_t>(v8::Local<v8::Value> val);
+Nan::Maybe<int64_t> Nan::To<int64_t>(v8::Local<v8::Value> val);
+Nan::Maybe<uint32_t> Nan::To<uint32_t>(v8::Local<v8::Value> val);
+```
+
+### Example
+
+```c++
+v8::Local<v8::Value> val;
+Nan::MaybeLocal<v8::String> str = Nan::To<v8::String>(val);
+Nan::Maybe<double> d = Nan::To<double>(val);
+```
+