doc: add more content to documentation

Nicola Del Gobbo · mhdawson · commit 5543c01f2d77 · 2017-11-23T14:29:51.000-05:00
PR-URL: #192 Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
diff --git a/README.md b/README.md
@@ -26,10 +26,11 @@ values. Concepts and operations generally map to ideas specified in the
 - **[Examples](#examples)**
 - **[Tests](#tests)**
 - **[More resource and info about native Addons](#resources)**
+- **[Code of Conduct](CODE_OF_CONDUCT.md)**
 - **[Contributors](#contributors)**
 - **[License](#license)**
 
-## **Current version: 1.0.0**
+## **Current version: 1.1.0**
 
 (See [CHANHELOG.md](CHANGELOG.md) for complete Changelog)
 
@@ -84,13 +85,29 @@ values. Concepts and operations generally map to ideas specified in the
 
 ### **Examples**
 
-//TODO  References to examples
+Are you new to **N-API**? Take a look at our **[examples](https://github.com/nodejs/abi-stable-node-addon-examples)**
+
+- **[Hello World](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/1_hello_world/node-addon-api)**
+- **[Pass arguments to a function](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/2_function_arguments/node-addon-api)**
+- **[Callbacks](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/3_callbacks/node-addon-api)**
+- **[Object factory](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/4_object_factory/node-addon-api)**
+- **[Function factory](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/4_object_factory/node-addon-api)**
+- **[Wrapping C++ Object](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/6_object_wrap/node-addon-api)**
+- **[Factory of wrapped object](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/7_factory_wrap/node-addon-api)**
+- **[Passing wrapped object around](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/8_passing_wrapped/node-addon-api)**
 
 <a name="tests"></a>
 
 ### **Tests**
 
-//TODO References to tests
+To run the **N-API** tests do:
+
+```
+npm install
+npm test
+```
+
+Take a look and get inspired by our **[test suite](https://github.com/nodejs/node-addon-api/tree/master/test)**
 
 <a name="resources"></a>
 
diff --git a/doc/array.md b/doc/array.md
@@ -0,0 +1,5 @@
+# Array
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/array_buffer.md b/doc/array_buffer.md
@@ -0,0 +1,5 @@
+# Array buffer
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/async_operations.md b/doc/async_operations.md
@@ -0,0 +1,5 @@
+# Asynchronous operations
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/async_worker.md b/doc/async_worker.md
@@ -0,0 +1,5 @@
+# Async worker
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/basic_types.md b/doc/basic_types.md
@@ -0,0 +1,5 @@
+# Basic Types
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/boolean.md b/doc/boolean.md
@@ -0,0 +1,5 @@
+# Boolean
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/buffer.md b/doc/buffer.md
@@ -0,0 +1,5 @@
+# Buffer
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/class_property_descriptor.md b/doc/class_property_descriptor.md
@@ -0,0 +1,5 @@
+# Class propertry and descriptior
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/cmake-js.md b/doc/cmake-js.md
@@ -0,0 +1,18 @@
+# CMake.js
+
+**CMake.js** is a build tool that allow native addon developer to compile their
+C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but
+instead of Google's **gyp** format it is base on **CMake** build system.
+
+## **CMake** reference
+
+  - [Installation](https://www.npmjs.com/package/cmake-js#installation)
+  - [How to use](https://www.npmjs.com/package/cmake-js#usage)
+  - [Tutorials](https://www.npmjs.com/package/cmake-js#tutorials)
+  - [Use case in the works - ArrayFire.js](https://www.npmjs.com/package/cmake-js#use-case-in-the-works---arrayfirejs)
+
+Sometimes finding the right settings is not easy so to accomplish at most
+complicated task please refer to:
+
+- [CMake documentation](https://cmake.org/)
+- [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki)
diff --git a/doc/conversion-tool.md b/doc/conversion-tool.md
@@ -1,7 +1,9 @@
-## Conversion Tool
+# Conversion Tool
 
-To make the migration to node-addon-api easier, we have provided a script to help
-complete the steps listed above. To use the conversion script:
+To make the migration to **node-addon-api** easier, we have provided a script to
+help complete some tasks.
+
+## To use the conversion script:
 
   1. Go to your module directory
 
@@ -14,15 +16,13 @@ cd [module_path]
 ```
 npm install node-addon-api
 ```
-
   3. Run node-addon-api conversion script
 
 ```
 node ./node_modules/node-addon-api/tools/conversion.js ./
 ```
 
   4. While this script makes conversion easier, it still cannot fully convert
-
 the module. The next step is to try to build the module and complete the
 remaining conversions necessary to allow it to compile and pass all of the
 module's tests.
diff --git a/doc/error.md b/doc/error.md
@@ -0,0 +1,5 @@
+# Error
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/error_handling.md b/doc/error_handling.md
@@ -0,0 +1,5 @@
+# Error handling
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/escapable_handle_sope.md b/doc/escapable_handle_sope.md
@@ -0,0 +1,5 @@
+# Escapable handle scope
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/function.md b/doc/function.md
@@ -0,0 +1,5 @@
+# Function
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/function_reference.md b/doc/function_reference.md
@@ -0,0 +1,5 @@
+# Function reference
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/generator.md b/doc/generator.md
@@ -0,0 +1,13 @@
+# Generator
+
+## What is generator
+
+**[generator-napi-module](https://www.npmjs.com/package/generator-napi-module)** is a module to quickly generate a skeleton module using
+**N-API**, the new API for Native addons. This module automatically sets up your
+**gyp file** to use **node-addon-api**, the C++ wrappers for N-API and generates
+a wrapper JS module. Optionally, it can even configure the generated project to
+use **TypeScript** instead.
+
+## **generator-napi-module** reference
+
+  - [Installation and usage](https://www.npmjs.com/package/generator-napi-module#installation)
diff --git a/doc/handle_scope.md b/doc/handle_scope.md
@@ -0,0 +1,5 @@
+# Handle scope
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/name.md b/doc/name.md
@@ -0,0 +1,5 @@
+# Name
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/node-gyp.md b/doc/node-gyp.md
@@ -0,0 +1,80 @@
+# node-gyp
+
+C++ code needs to be compiled into executable form whether it be as an object
+file to linked with others, a shared library, or a standalone executable.
+
+The main reason for this is that we need to link to the Node.js dependencies and
+headers correcrtly, another reason is that we need a cross platform way to build
+C++ soucre into binary for the target platform,
+
+Until now **node-gyp** is the **de-fafto** standard build tool for writing
+Node.js addons. It's based on Google's **gyp** build tool, which abstract away
+many of the tedious issues related to cross platform building.
+
+**node-gyp** uses a file called ```binding.gyp``` that is located on the root of
+your addon project.
+
+```binding.gyp``` file, contains all building configurations organized with a
+JSON like syntax. The most important parameter is the  **target** that must be
+set to the same value used on the initialization code of the addon as in the
+examples reported below:
+
+### **binding.gyp**
+
+```gyp
+{
+  "targets": [
+    {
+      # myModule is the name of your native addon
+      "target_name": "myModule",
+      "sources": ["src/my_module.cc", ...],
+      ...
+  ]
+}
+```
+
+### **my_module.cc**
+
+```cpp
+#include <napi.h>
+
+// ...
+
+/**
+* This code is our entry-point. We receive two arguments here, the first is the
+* environment that represent an independent instance of the JavaScript runtime,
+* the second is exports, the same as module.exports in a .js file.
+* You can either add properties to the exports object passed in or create your
+* own exports object. In either case you must return the object to be used as
+* the exports for the module when you return from the Init function.
+*/
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+
+  // ...
+
+  return exports;
+}
+
+/**
+* This code defines the entry-point for the Node addon, it tells Node where to go
+* once the library has been loaded into active memory. The first argument must
+* match the "target" in our *binding.gyp*. The second argument points to the
+* function to invoke.
+*/
+NODE_API_MODULE(myModule, Init)
+```
+
+## **node-gyp** reference
+
+  - [Installation](https://www.npmjs.com/package/node-gyp#installation)
+  - [How to use](https://www.npmjs.com/package/node-gyp#how-to-use)
+  - [The binding.gyp file](https://www.npmjs.com/package/node-gyp#the-bindinggyp-file)
+  - [Commands](https://www.npmjs.com/package/node-gyp#commands)
+  - [Command options](https://www.npmjs.com/package/node-gyp#command-options)
+  - [Configuration](https://www.npmjs.com/package/node-gyp#configuration)
+
+Sometimes finding the right settings for ```binding.gyp``` is not easy so to
+accomplish at most complicated task please refer to:
+
+- [GYP documentation](https://gyp.gsrc.io/index.md)
+- [node-gyp wiki](https://github.com/nodejs/node-gyp/wiki)
diff --git a/doc/object.md b/doc/object.md
@@ -0,0 +1,5 @@
+# Object
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/object_reference.md b/doc/object_reference.md
@@ -0,0 +1,5 @@
+# Object reference
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/object_wrap.md b/doc/object_wrap.md
@@ -6,4 +6,8 @@ JavaScript code to a C++ object.
 Classes extending ```ObjectWrap``` can be instantiated from JavaScript using the
 **new** operator, and their methods can be directly invoked from JavaScript.
 The **wrap** word refers to a way to group methods and state of your class because it
-will be your responsibility write custom code to bridge each of your C++ class methods.
+will be your responsibility write custom code to bridge each of your C++ class methods.
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/onject_lifetime_management.md b/doc/onject_lifetime_management.md
@@ -0,0 +1,5 @@
+# Object lifetime management
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/promises.md b/doc/promises.md
@@ -0,0 +1,5 @@
+# Promise
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/property_descriptor.md b/doc/property_descriptor.md
@@ -0,0 +1,5 @@
+# property descriptor
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/reference.md b/doc/reference.md
@@ -0,0 +1,5 @@
+# Reference
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/setup.md b/doc/setup.md
@@ -1,6 +1,19 @@
-## Setup
+# Setup
 
-To use N-API in a native module:
+## Prerequisites
+
+Before starting to use **N-API** you need to assure you have the following
+prerequisites:
+
+* **Node.JS** see: [Installing Node.js](https://nodejs.org/)
+
+* **Node.js native addon build tool**
+
+  - **[node-gyp](node-gyp.md)**
+
+## Installation and usage
+
+To use **N-API** in a native module:
 
   1. Add a dependency on this package to `package.json`:
 
diff --git a/doc/string.md b/doc/string.md
@@ -0,0 +1,5 @@
+# String
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/symbol.md b/doc/symbol.md
@@ -0,0 +1,5 @@
+# Symbol
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/typed_array.md b/doc/typed_array.md
@@ -0,0 +1,5 @@
+# Typed array
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/typed_array_of.md b/doc/typed_array_of.md
@@ -0,0 +1,5 @@
+# Typed array of
+
+You are reading a draft of the next documentation and it's in continuos update so
+if you don't find what you need please refer to:
+[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
diff --git a/doc/working_with_javascript_values.md b/doc/working_with_javascript_values.md
