Auto merge of #408 - fitzgen:clean-up-docs, r=emilio

Clean up the README.md and CONTRIBUTING.md docs

Use the `doctoc` program to generate tables of contents, stop referring
to forking and make this the canonical `bindgen`, move the section on
building to last.

r? @emilio

2 files changed, 137 insertions, 80 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bab631d6..c1ec96d1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,28 +1,35 @@
-# Contributing to `servo/rust-bindgen`
+# Contributing to `bindgen`
 
 Hi! We'd love to have your contributions! If you want help or mentorship, reach
-out to us in a GitHub issue, or stop by #servo on irc.mozilla.org and introduce
-yourself.
-
-* [Code of Conduct](#coc)
-* [Filing an Issue](#issue)
-* [Building](#building)
-* [Testing](#tests)
-  * [Overview](#tests-overview)
-  * [Running All Tests](#tests-all)
-  * [Running a Single, Specific Test](#tests-one)
-  * [Authoring New Tests](#tests-new)
-* [Automatic Code Formatting](#formatting)
-* [Debug Logging](#logs)
-* [Using `creduce` to Minimize Test Cases](#creduce)
-
-## Code of Conduct <span id="coc"/>
+out to us in a GitHub issue, or stop by
+[#servo on irc.mozilla.org](irc://irc.mozilla.org#servo) and introduce yourself.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Code of Conduct](#code-of-conduct)
+- [Filing an Issue](#filing-an-issue)
+- [Building](#building)
+- [Testing](#testing)
+  - [Overview](#overview)
+  - [Running All Tests](#running-all-tests)
+  - [Authoring New Tests](#authoring-new-tests)
+- [Automatic code formatting](#automatic-code-formatting)
+- [Debug Logging](#debug-logging)
+- [Using `creduce` to Minimize Test Cases](#using-creduce-to-minimize-test-cases)
+  - [Isolating Your Test Case](#isolating-your-test-case)
+  - [Writing a Predicate Script](#writing-a-predicate-script)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Code of Conduct
 
 We abide by the [Rust Code of Conduct][coc] and ask that you do as well.
 
 [coc]: https://www.rust-lang.org/en-US/conduct.html
 
-## Filing an Issue <span id="issue"/>
+## Filing an Issue
 
 Think you've found a bug? File an issue! To help us understand and reproduce the
 issue, provide us with:
@@ -33,11 +40,39 @@ issue, provide us with:
 * The actual `bindgen` output
 * The [debugging logs](#logs) generated when running `bindgen` on this testcase
 
-## Building <span id="building"/>
+## Building
+
+To build `libbindgen`:
+
+```
+$ cd bindgen/libbindgen
+$ cargo build
+```
+
+To build the `bindgen` executable:
 
-Build instructions are in the [README](./README.md).
+```
+$ cd bindgen/bindgen
+$ cargo build
+```
+
+If you installed multiple versions of llvm, it may not be able to locate the
+latest version of libclang. In that case, you may want to either uninstall other
+versions of llvm, or specify the path of the desired libclang explicitly:
+
+```
+$ export LIBCLANG_PATH=path/to/clang-3.9/lib
+```
+
+On Linux and macOS, you may also need to add a path to `libclang.so` (usually
+the same path as above) to library search path. This can be done as below:
+
+```
+$ export LD_LIBRARY_PATH=path/to/clang-3.9/lib # for Linux
+$ export DYLD_LIBRARY_PATH=path/to/clang-3.9/lib # for macOS
+```
 
-Additionally, you may want to build and test with the `_docs` feature to ensure
+Additionally, you may want to build and test with the `docs_` feature to ensure
 that you aren't forgetting to document types and functions. CI will catch it if
 you forget, but the turn around will be a lot slower ;)
 
@@ -45,27 +80,28 @@ you forget, but the turn around will be a lot slower ;)
 $ cd libbindgen && cargo build --features "llvm_stable _docs"
 ```
 
-## Testing <span id="tests"/>
+## Testing
 
 Code for binding generation and testing thereof is in the `libbindgen` crate.
 The following sections assume you are working in that subdirectory.
 
-### Overview <span id="tests-overview"/>
+### Overview
 
-Input C/C++ test headers reside in the `tests/headers` directory. Expected
-output Rust bindings live in `tests/expectations/tests`. For example,
-`tests/headers/my_header.h`'s expected generated Rust bindings would be
-`tests/expectations/tests/my_header.rs`.
+Input C/C++ test headers reside in the `libbindgen/tests/headers`
+directory. Expected output Rust bindings live in
+`libbindgen/tests/expectations/tests`. For example,
+`libbindgen/tests/headers/my_header.h`'s expected generated Rust bindings would
+be `libbindgen/tests/expectations/tests/my_header.rs`.
 
 Run `cargo test` to compare generated Rust bindings to the expectations.
 
-### Running All Tests <span id="tests-all"/>
+### Running All Tests
 
 ```
 $ cargo test [--features llvm_stable]
 ```
 
-### Authoring New Tests <span id="tests-new"/>
+### Authoring New Tests
 
 To add a new test header to the suite, simply put it in the `tests/headers`
 directory. Next, run `bindgen` to generate the initial expected output Rust
@@ -84,7 +120,7 @@ Then verify the new Rust bindings compile and pass some basic tests:
 $ cargo test -p tests_expectations
 ```
 
-## Automatic code formatting <span id="formatting"/>
+## Automatic code formatting
 
 There's a `rustfmt.toml` file in the repo. Ideally changes should be consistent
 with the style, though that's not enforced right now.
@@ -105,10 +141,10 @@ $ cargo install rustfmt
 
 And ensure `~/.cargo/bin` is on your path.
 
-## Debug Logging <span id="logs"/>
+## Debug Logging
 
 To help debug what `bindgen` is doing, you can define the environment variable
-`RUST_LOG=bindgen` to get a bunch of debugging log spew.
+`RUST_LOG=libbindgen` to get a bunch of debugging log spew.
 
 ```
 $ RUST_LOG=libbindgen ./target/debug/bindgen [flags...] ~/path/to/some/header.h
@@ -117,10 +153,11 @@ $ RUST_LOG=libbindgen ./target/debug/bindgen [flags...] ~/path/to/some/header.h
 This logging can also be used when debugging failing tests:
 
 ```
-$ RUST_LOG=libbindgen cd libbindgen && cargo test
+$ cd libbindgen
+$ RUST_LOG=libbindgen cargo test
 ```
 
-## Using `creduce` to Minimize Test Cases <span id="creduce"/>
+## Using `creduce` to Minimize Test Cases
 
 If you are hacking on `bindgen` and find a test case that causes an unexpected
 panic, results in bad Rust bindings, or some other incorrectness in `bindgen`,
diff --git a/README.md b/README.md
index 3b3f56e6..15ef6db2 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,63 @@
-# Servo's rust-bindgen
+# `bindgen`
 
-A binding generator for the Rust language.
+Automatically generates Rust FFI bindings to C and C++ libraries.
 
-This is a fork of [crabtw/rust-bindgen](https://github.com/crabtw/rust-bindgen)
-designed to work on C++ code as well.
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-Currently this is being used for Servo's SpiderMonkey bindings, and also for
-the [Stylo](https://public.etherpad-mozilla.org/p/stylo) project.
 
-## Requirements
+- [Usage](#usage)
+  - [Requirements](#requirements)
+    - [Installing Clang 3.9](#installing-clang-39)
+      - [Windows](#windows)
+      - [OSX](#osx)
+      - [Debian-based Linuxes](#debian-based-linuxes)
+      - [Arch](#arch)
+      - [From source](#from-source)
+  - [Library usage with `build.rs`](#library-usage-with-buildrs)
+    - [`build.rs` Tutorial](#buildrs-tutorial)
+    - [Simple Example: `./bindgen-integration`](#simple-example-bindgen-integration)
+    - [Real World Example: Stylo](#real-world-example-stylo)
+  - [Command Line Usage](#command-line-usage)
+  - [C++](#c)
+  - [Annotations](#annotations)
+    - [`opaque`](#opaque)
+    - [`hide`](#hide)
+    - [`replaces`](#replaces)
+    - [`nocopy`](#nocopy)
+- [Building From Source](#building-from-source)
 
-It is recommended to use clang 3.9 with the current generator. It can run with
-clang 3.8 with some features disabled.
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-### Installing Clang 3.9
+## Usage
 
-#### Windows
+### Requirements
+
+It is recommended to use Clang 3.9 or greater, however `bindgen` can run with
+older Clangs with some features disabled.
+
+#### Installing Clang 3.9
+
+##### Windows
 
 Download and install the official pre-built binary from
 [LLVM download page](http://releases.llvm.org/download.html).
 
-#### OSX
+##### OSX
 
 If you use Homebrew:
+
 ```
 $ brew install llvm
 ```
 
 If you use MacPorts:
+
 ```
 $ port install clang-3.9
 ```
 
-#### Debian-based Linuxes
+##### Debian-based Linuxes
 
 ```
 # apt-get install llvm-3.9-dev libclang-3.9-dev
@@ -42,13 +67,13 @@ Ubuntu 16.10 provides the necessary packages directly. If you are using older
 version of Ubuntu or other Debian-based distros, you may need to add the LLVM
 repos to get version 3.9. See http://apt.llvm.org/.
 
-#### Arch
+##### Arch
 
 ```
 # pacman -S clang
 ```
 
-#### From source
+##### From source
 
 If your package manager doesn't yet offer Clang 3.9, you'll need to build from
 source. For that, follow the instructions
@@ -61,31 +86,26 @@ Those instructions list optional steps. For bindgen:
 * Checkout and build the compiler-rt
 * You do not need to checkout or build libcxx
 
-## Building
+### Library usage with `build.rs`
 
-```
-$ cd bindgen
-$ cargo build
-```
+#### `build.rs` Tutorial
 
-If you installed multiple versions of llvm, it may not be able to locate the
-latest version of libclang. In that case, you may want to either uninstall
-other versions of llvm, or specify the path of the desired libclang explicitly:
-```
-$ export LIBCLANG_PATH=path/to/clang-3.9/lib
-```
+[Here is a step-by-step tutorial for generating FFI bindings to the `bzip2` C library.][tutorial]
 
-On Linux and macOS, you may also need to add a path to `libclang.so` (usually
-the same path as above) to library search path. This can be done as below:
-```
-$ export LD_LIBRARY_PATH=path/to/clang-3.9/lib # for Linux
-$ export DYLD_LIBRARY_PATH=path/to/clang-3.9/lib # for macOS
-```
+[tutorial]: http://fitzgeraldnick.com/2016/12/14/using-libbindgen-in-build-rs.html
+
+#### Simple Example: `./bindgen-integration`
 
-# Library usage with `build.rs`
+The [`./bindgen-integration`][integration] directory has an example crate that
+generates FFI bindings in `build.rs` and can be used a template for new
+projects.
 
-See [the Stylo build script][stylo-script] to see how it is used inside the
-Servo organisation.
+[integration]: ./bindgen-integration
+
+#### Real World Example: Stylo
+
+A real world example is [the Stylo build script][stylo-script] used for
+integrating Servo's layout system into Gecko.
 
 [stylo-script]: https://github.com/servo/servo/blob/master/components/style/build_gecko.rs
 
@@ -124,28 +144,28 @@ In `src/main.rs`:
 include!(concat!(env!("OUT_DIR"), "/example.rs"));
 ```
 
-# Command Line Usage
+### Command Line Usage
 
-There are a few options documented when running `./bindgen --help`. Other
-options might exist (see [the SpiderMonkey script][sm-script] to see how it
-is used inside the Servo organisation.
+```
+$ cargo install bindgen
+```
 
-[sm-script]: https://github.com/servo/rust-mozjs/blob/master/etc/bindings.sh
+There are a few options documented when running `./bindgen --help`.
 
-## C++ Usage
+### C++
 
 This fork of rust-bindgen can handle a number of C++ features.
 
 When passing in header files, the file will automatically be treated as C++ if
 it ends in ``.hpp``. If it doesn't, ``-x c++`` can be used to force C++ mode.
 
-## Annotations
+### Annotations
 
 The translation of classes, structs, enums, and typedefs can be adjusted using
 annotations. Annotations are specifically formatted html tags inside doxygen
 style comments.
 
-### `opaque`
+#### `opaque`
 
 The `opaque` annotation instructs bindgen to ignore all fields defined in
 a struct/class.
@@ -154,7 +174,7 @@ a struct/class.
 /// <div rustbindgen opaque></div>
 ```
 
-### `hide`
+#### `hide`
 
 The `hide` annotation instructs bindgen to ignore the struct/class/field/enum
 completely.
@@ -163,7 +183,7 @@ completely.
 /// <div rustbindgen hide></div>
 ```
 
-### `replaces`
+#### `replaces`
 
 The `replaces` annotation can be used to use a type as a replacement for other
 (presumably more complex) type. This is used in Stylo to generate bindings for
@@ -188,7 +208,7 @@ public:
 That way, after code generation, the bindings for the `nsTArray` type are
 the ones that would be generated for `nsTArray_Simple`.
 
-### `nocopy`
+#### `nocopy`
 
 The `nocopy` annotation is used to prevent bindgen to autoderive the `Copy`
 and `Clone` traits for a type.