doc: Scaffolding for documentation

PR-URL: nodejs/node-addon-api#168 Reviewed-By: Michael Dawson <[email protected]>
kevindavies8 · Nov 1, 2017 · 33b7bf2 · 33b7bf2
1 parent 938fde4
commit 33b7bf2
Show file tree

Hide file tree

Showing 39 changed files with 200 additions and 83 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1 @@
+# Node.js API (N-API) Package Changelog
diff --git a/README.md b/README.md
@@ -1,86 +1,106 @@
-# Node.js API (N-API) Package
-
-This package contains header-only C++ wrapper classes for the ABI-stable
-Node.js API (N-API), along with library code that enables
-backward-compatibility with use with older versions of Node.js that do
-not have N-API built-in.
-
-### API Documentation
-
- - [ABI-Stable C APIs in Node.js](https://nodejs.org/api/n-api.html)
- - [C++ APIs in this package](https://nodejs.github.io/node-addon-api/namespace_napi.html)
-
-### Getting Started
-
-To use N-API in a native module:
-  1. Add a dependency on this package to `package.json`:
-```json
-  "dependencies": {
-    "node-addon-api": "1.0.0",
-  }
-```
-
-  2. Reference this package's include directory and gyp file in `binding.gyp`:
-```gyp
-  'include_dirs': ["<!@(node -p \"require('node-addon-api').include\")"],
-  'dependencies': ["<!(node -p \"require('node-addon-api').gyp\")"],
-```
-
-  3. Decide whether the package will enable C++ exceptions in the N-API wrapper.
-     The base ABI-stable C APIs do not throw or handle C++ exceptions, but the
-     N-API C++ wrapper classes may _optionally_
-     [integrate C++ and JavaScript exception-handling
-     ](https://nodejs.github.io/node-addon-api/class_napi_1_1_error.html).
-     To enable that capability, C++ exceptions must be enabled in `binding.gyp`:
-```gyp
-  'cflags!': [ '-fno-exceptions' ],
-  'cflags_cc!': [ '-fno-exceptions' ],
-  'xcode_settings': {
-    'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
-    'CLANG_CXX_LIBRARY': 'libc++',
-    'MACOSX_DEPLOYMENT_TARGET': '10.7',
-  },
-  'msvs_settings': {
-    'VCCLCompilerTool': { 'ExceptionHandling': 1 },
-  },
-```
-  Alternatively, disable use of C++ exceptions in N-API:
-```gyp
-  'defines': [ 'NAPI_DISABLE_CPP_EXCEPTIONS' ],
-```
-
-  4. Include `napi.h` in the native module code.
-     To ensure only ABI-stable APIs are used, DO NOT include
-     `node.h`, `nan.h`, or `v8.h`.
-```C++
-#include "napi.h"
-```
-
-At build time, the N-API back-compat library code will be used only when the
-targeted node version *does not* have N-API built-in.
-
-## 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:
-  1. Go to your module directory
-```
-cd [module_path]
-```
-  2. Install node-addon-api module
-```
-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.
-
-
-<a name="collaborators"></a>
+# **Node.js API (N-API) Package**
+
+This package contains **header-only C++ wrapper classes** for the **ABI-stable
+Node.js API**  also known as **N-API**, providing C++ object model and exception
+handling semantics with low overhead. It guarantees backward compatibility with
+use with older versions of Node.js that do not have N-API built-in.
+
+Node.js API guarentees the **API** and **ABI** compatibility across different
+version of Node.js. So if you switch to a
+different version of Node.js you must not reinstall and maybe recompile the
+Addon.
+
+N-API is an API for building native Addons. It is independent from the underlying
+JavaScript runtime (ex V8) and is maintained as part of Node.js itself. This API
+will be Application Binary Interface (ABI) stable across versions of Node.js. It
+is intended to insulate Addons from changes in the underlying JavaScript engine
+and allow modules compiled for one version to run on later versions of Node.js
+without recompilation.
+
+APIs exposed by N-API are generally used to create and manipulate JavaScript
+values. Concepts and operations generally map to ideas specified in the
+**ECMA262 Language Specification**.
+
+- **[Setup](#setup)**
+- **[API Documentation](#api)**
+- **[Examples](#examples)**
+- **[Tests](#tests)**
+- **[More resource and info about native Addons](#resources)**
+- **[Contributors](#contributors)**
+- **[License](#license)**
+
+## **Current version: 1.0.0**
+
+(See [CHANHELOG.md](CHANGELOG.md) for complete Changelog)
+
+[![NPM](https://nodei.co/npm/node-addon-api.png?downloads=true&downloadRank=true)](https://nodei.co/npm/dode-addon-api/) [![NPM](https://nodei.co/npm-dl/node-addon-api.png?months=6&height=1)](https://nodei.co/npm/dode-addon-api/)
+
+<a name="setup"></a>
+
+## Setup
+  - [Installation and usage](doc/setup.md)
+  - [node-gyp](doc/node-gyp.md)
+  - [cmake-js](doc/cmake-js.md)
+  - [Conversion tool](doc/conversion-tool.md)
+  - [Generator](doc/generator.md)
+
+<a name="api"></a>
+
+### **API Documentation**
+ - [Basic Types](doc/basic_types.md)
+    - [Array](doc/array.md)
+    - [Symbol](doc/symbol.md)
+    - [String](doc/string.md)
+    - [Name](doc/name.md)
+    - [Number](doc/number.md)
+    - [Boolean](doc/boolean.md)
+    - [Env](doc/env.md)
+    - [Value](doc/value.md)
+    - [CallbackInfo](doc/callbackinfo.md)
+    - [Reference](doc/reference.md)
+    - [External](doc/external.md)
+    - [Object](doc/object.md)
+        - [ObjectReference](doc/object_reference.md)
+        - [PropertyDescriptor](doc/property_descriptor.md)
+ - [Error Handling](doc/error_handling.md)
+    - [Error](doc/error.md)
+ - [Object Lifettime Management](doc/object_lifetime_management.md)
+    - [HandleScope](doc/handle_scope.md)
+    - [EscapableHandleScope](doc/escapable_handle_scope.md)
+ - [Working with JavaScript Values](doc/working_with_javascript_values.md)
+    - [Function](doc/function.md)
+        - [FunctionReference](doc/function_reference.md)
+    - [ObjectWrap](doc/object_wrap.md)
+        - [ClassPropertyDescriptor](doc/class_property_descriptor.md)
+    - [Buffer](doc/buffer.md)
+    - [ArrayBuffer](doc/array_buffer.md)
+    - [TypedArray](doc/typed_array.md)
+      - [TypedArrayOf](doc/typed_array_of.md)
+ - [Async Operations](doc/async_operations.md)
+    - [AsyncWorker](async_worker.md)
+ - [Promises](doc/promises.md)
+
+<a name="examples"></a>
+
+### **Examples**
+
+//TODO  References to examples
+
+<a name="tests"></a>
+
+### **Tests**
+
+//TODO References to tests
+
+<a name="resources"></a>
+
+### **More resource and info about native Addons**
+- **[C++ Addons](https://nodejs.org/dist/latest/docs/api/addons.html)**
+- **[N-API](https://nodejs.org/dist/latest/docs/api/n-api.html)**
+- **[N-API - Next Generation Node API for Native Modules](https://youtu.be/-Oniup60Afs)**
+
+<a name="contributors"></a>
+
 ### WG Members / Collaborators
 | Name                | GitHub link                                           |
 | ------------------- | ----------------------------------------------------- |
@@ -93,3 +113,7 @@ module's tests.
 | Michael Dawson      | [mhdawson](https://github.com/mhdawson)               |
 | Sampson Gao         | [sampsongao](https://github.com/sampsongao)           |
 | Taylor Woll         | [boingoing](https://github.com/boingoing)             |
+
+<a name="license"></a>
+
+Licensed under [MIT](./LICENSE.md)
diff --git a/doc/array.md b/doc/array.md
diff --git a/doc/array_buffer.md b/doc/array_buffer.md
diff --git a/doc/async_operations.md b/doc/async_operations.md
diff --git a/doc/async_worker.md b/doc/async_worker.md
diff --git a/doc/basic_types.md b/doc/basic_types.md
diff --git a/doc/boolean.md b/doc/boolean.md
diff --git a/doc/buffer.md b/doc/buffer.md
diff --git a/doc/callbackinfo.md b/doc/callbackinfo.md
diff --git a/doc/class_property_descriptor.md b/doc/class_property_descriptor.md
diff --git a/doc/cmake-js.md b/doc/cmake-js.md
diff --git a/doc/conversion-tool.md b/doc/conversion-tool.md
@@ -0,0 +1,28 @@
+## 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:
+
+  1. Go to your module directory
+
+```
+cd [module_path]
+```
+
+  2. Install node-addon-api module
+
+```
+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/env.md b/doc/env.md
diff --git a/doc/error.md b/doc/error.md
diff --git a/doc/error_handling.md b/doc/error_handling.md
diff --git a/doc/escapable_handle_sope.md b/doc/escapable_handle_sope.md
diff --git a/doc/external.md b/doc/external.md
diff --git a/doc/function.md b/doc/function.md
diff --git a/doc/function_reference.md b/doc/function_reference.md
diff --git a/doc/generator.md b/doc/generator.md
diff --git a/doc/handle_scope.md b/doc/handle_scope.md
diff --git a/doc/name.md b/doc/name.md
diff --git a/doc/node-gyp.md b/doc/node-gyp.md
diff --git a/doc/number.md b/doc/number.md
diff --git a/doc/object.md b/doc/object.md
diff --git a/doc/object_reference.md b/doc/object_reference.md
diff --git a/doc/object_wrap.md b/doc/object_wrap.md
@@ -0,0 +1,9 @@
+## Object Wrap
+
+The ```ObjectWrap``` class can be used to expose C++ code to JavaScript. To do
+this you need to extend the ObjectWrap class that contain all the plumbing to connect
+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.
diff --git a/doc/onject_lifetime_management.md b/doc/onject_lifetime_management.md
diff --git a/doc/promises.md b/doc/promises.md
diff --git a/doc/property_descriptor.md b/doc/property_descriptor.md
diff --git a/doc/reference.md b/doc/reference.md
diff --git a/doc/setup.md b/doc/setup.md
@@ -0,0 +1,55 @@
+## Setup
+
+To use N-API in a native module:
+
+  1. Add a dependency on this package to `package.json`:
+
+```json
+  "dependencies": {
+    "node-addon-api": "1.0.0",
+  }
+```
+
+  2. Reference this package's include directory and gyp file in `binding.gyp`:
+
+```gyp
+  'include_dirs': ["<!@(node -p \"require('node-addon-api').include\")"],
+  'dependencies': ["<!(node -p \"require('node-addon-api').gyp\")"],
+```
+
+  3. Decide whether the package will enable C++ exceptions in the N-API wrapper.
+     The base ABI-stable C APIs do not throw or handle C++ exceptions, but the
+     N-API C++ wrapper classes may _optionally_
+     [integrate C++ and JavaScript exception-handling
+     ](https://nodejs.github.io/node-addon-api/class_napi_1_1_error.html).
+     To enable that capability, C++ exceptions must be enabled in `binding.gyp`:
+
+```gyp
+  'cflags!': [ '-fno-exceptions' ],
+  'cflags_cc!': [ '-fno-exceptions' ],
+  'xcode_settings': {
+    'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
+    'CLANG_CXX_LIBRARY': 'libc++',
+    'MACOSX_DEPLOYMENT_TARGET': '10.7',
+  },
+  'msvs_settings': {
+    'VCCLCompilerTool': { 'ExceptionHandling': 1 },
+  },
+```
+
+  Alternatively, disable use of C++ exceptions in N-API:
+
+```gyp
+  'defines': [ 'NAPI_DISABLE_CPP_EXCEPTIONS' ],
+```
+
+  4. Include `napi.h` in the native module code.
+     To ensure only ABI-stable APIs are used, DO NOT include
+     `node.h`, `nan.h`, or `v8.h`.
+
+```C++
+#include "napi.h"
+```
+
+At build time, the N-API back-compat library code will be used only when the
+targeted node version *does not* have N-API built-in.
diff --git a/doc/string.md b/doc/string.md
diff --git a/doc/symbol.md b/doc/symbol.md
diff --git a/doc/typed_array.md b/doc/typed_array.md
diff --git a/doc/typed_array_of.md b/doc/typed_array_of.md
diff --git a/doc/value.md b/doc/value.md
diff --git a/doc/working_with_javascript_values.md b/doc/working_with_javascript_values.md