Add clang tidy/format docs

CONTRIBUTING.md

@@ -10,9 +10,9 @@ If adding new code, be sure to include relevant code comments. Code comments are
 
 Be sure to update any documentation relevant to your change. This includes updating the [CHANGELOG.md](https://github.com/mapbox/node-cpp-skel/blob/master/CHANGELOG.md).
 
-## Code Formatting
+## [Code Formatting](/docs/extended-tour.md#clang-tools)
 
-We use [this script](/scripts/format.sh#L20) to install a consistent version of [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) to format the code base. The format is automatically checked via a Travis CI build as well. Run the following script locally to ensure formatting is ready to merge:
+We use [this script](/scripts/clang-format.sh#L20) to install a consistent version of [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) to format the code base. The format is automatically checked via a Travis CI build as well. Run the following script locally to ensure formatting is ready to merge:
 
     make format
 

docs/extended-tour.md

@@ -8,6 +8,7 @@ Welcome to the extended tour of node-cpp-skel. This documentation is especially
 - [Configuration files](extended-tour.md#configuration-files)
 - [Autogenerated files](extended-tour.md#autogenerated-files)
 - [Overall flow](extended-tour.md#overall-flow)
+- [Clang Tools](extended-tour.md#clang-tools)
 - [Xcode](extended-tour.md#xcode)
 
 # Walkthrough example code
@@ -172,6 +173,40 @@ User of your module runs 'npm install'
 
 This binary file `../lib/binding/module.node` is what `require()` points to within Node.js.
 
+# Clang Tools
+
+This skeleton uses two clang/llvm tools for automated formatting and static fixes. 
+
+Each of these tools run within their own [Travis jobs](https://github.com/mapbox/node-cpp-skel/blob/master/.travis.yml). You can disable these Travis jobs if you'd like, by commenting them out in `.travis.yml`. This may be necessary if you're porting this skel into an already-existing project that triggers tons of clang-tidy errors, and you'd like to work through them gradually while still actively iterating on other parts of your code.
+
+### [clang-format](https://clang.llvm.org/docs/ClangFormat.html)
+Automates coding style enforcement, for example whitespace, tabbing, wrapping.
+
+To run
+```
+make format
+```
+
+- Set format preferences in [`.clang-format`](https://github.com/mapbox/node-cpp-skel/blob/master/.clang-format)
+- Installed and run via [`/scripts/clang-format.sh`](https://github.com/mapbox/node-cpp-skel/blob/master/scripts/clang-format.sh)
+
+
+### [clang-tidy](https://clang.llvm.org/extra/clang-tidy/)
+Lint framework that can do very powerful checks, for example bugs that can be deduced via [static analysis](https://github.com/mapbox/cpp/blob/master/glossary.md#static-analysis), unneeded copies, inefficient for-loops, and improved readability. In many cases, it can fix and modernize your code.
+
+To run
+```
+make tidy
+```
+
+- The clang-tidy tool has a large set of checks and when one fails, the error message contains the shorthand for the check name. See llvm's docs for details about what failed check is referring to. For example, see ["performance-unnecessary-copy-initialization"](https://clang.llvm.org/extra/clang-tidy/checks/performance-unnecessary-copy-initialization.html).
+- Set tidy preferences in [`.clang-tidy`](https://github.com/mapbox/node-cpp-skel/blob/master/.clang-tidy). When you run clang-tidy, you'll see output of a number of specific checks that tidy runs. You can add/remove any of these checks via the `.clang-tidy` file, configure these checks, and specify the files you'd like to run these checks against. The skel runs clang-tidy against everything within the `/src` directory.
+- This skel runs clang-tidy with the `-fix` option, which will automatically apply fixes to your code. Though some warnings will need to be fixed manually.
+- Installed and run via [`/scripts/clang-tidy.sh`](https://github.com/mapbox/node-cpp-skel/blob/master/scripts/clang-tidy.sh)
+- `NOLINT`: In the case that clang-tidy throws for code that you either want to keep as-is or can't control, you can [use `NOLINT`](https://github.com/mapbox/node-cpp-skel/blob/87c8d51f2d7d05ac44f3ea7a607f60e73a2af9c8/src/module.cpp#L43-L46) to silent clang-tidy.
+- Since clang-tidy must compile the code to do its checks, skel [generates](https://github.com/mapbox/node-cpp-skel/blob/master/scripts/generate_compile_commands.py) a JSON file that tells clang-tidy which files to run against and what compile command to run. This newly generated file, `/build/compile_command.json`, is created when running `make tidy`. See [clang's JSON compilation format docs](https://clang.llvm.org/docs/JSONCompilationDatabase.html) for more info.
+
+
 # Xcode
 
 ![npm-test scheme in Xcode](https://cloud.githubusercontent.com/assets/52399/16448893/4967a454-3df4-11e6-8bb5-701fe46174ef.png)