docs for in-process hooks

Author: tailsu

README.md

@@ -12,7 +12,7 @@ How to use
 
 ### Describe the hooks
 First, add a description of your hooks to the module's `package.json`. Here's an example:
-```
+```json
 {
   "nativescript": {
     "hooks": [
@@ -54,4 +54,53 @@ NativeScript modules that install hooks are intended to be installed using the `
 * `TNS_HOOKS_DIR` - the directory where the hooks should be installed. It may or may not exist.
 * `TNS_PROJECT_DIR` - the current project directory.
 
-Modules installed this way can be uninstalled using `npm rm --save-dev`.
+Modules installed this way can be uninstalled simply by running `npm rm --save-dev`.
+
+In-process hooks
+----------------
+By default, hooks are executed in a child process and execution continues when the child process dies. This gives you flexibility when writing your hooks, but doesn't allow you to use any of the services of the CLI.
+
+To that end, in-process hooks allow you to execute your hooks in such a way so that you can use any of the services available from the injector. In-process hooks work only for JavaScript hooks. To enable in-process execution, all you need to have is a `module.exports = ...` statement in the hook. For example, if the hook script is:
+```javascript
+module.exports = function($logger) {
+};
+```
+Then, the hook script will be require'd by the CLI and the exported function will be called through the injector.
+
+Hooks can take a special injected argument named `hookArgs`:
+```javascript
+module.exports = function(hookArgs) {
+};
+```
+`hookArgs` is a hash containing all the arguments passed to the hooked method. For example, the `prepare` hook is activated by the CLI method `preparePlatform(platform: string)`. Here, the hook will get the value of the `platform` argument in the `hookArgs.platform` property.
+
+If you execute asynchronous code in your hook, you need to return a promise, otherwise execution will continue before your hook completes:
+```javascript
+var mkdirp = require('mkdirp');
+module.exports = function($logger) {
+  return new Promise(function(resolve, reject) {
+      mkdirp('somedir', function(err) {
+          if (err) {
+            reject(err);
+          else {
+            resolve();
+          }
+        })
+    });
+}
+```
+
+And finally, when installing in-process hooks through this module, you need to explicitly specify that using the `inject` property of the script descriptor in the `package.json`:
+```json
+{
+  "nativescript": {
+    "hooks": [
+      {
+        "type": "after-prepare",
+        "script": "lib/after-prepare.js",
+        "inject": true
+      }
+    ]
+  },
+}
+```