Auto merge of rust-lang#419 - fitzgen:cargo-metadata, r=emilio

Small cargo and docs clean ups

r? @emilio

Author: bors-servo

CONTRIBUTING.md

@@ -42,19 +42,12 @@ issue, provide us with:
 
 ## Building
 
-To build `bindgen`:
+To build the `bindgen` library and the `bindgen` executable:
 
 ```
 $ cargo build
 ```
 
-To build the `bindgen` executable:
-
-```
-$ 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:

Cargo.toml

@@ -2,11 +2,12 @@
 authors = [
   "Jyun-Yan You <[email protected]>",
   "Emilio Cobos Álvarez <[email protected]>",
+  "Nick Fitzgerald <[email protected]>",
   "The Servo project developers",
 ]
-description = "A binding generator for Rust"
+description = "Automatically generates Rust FFI bindings to C and C++ libraries."
 keywords = ["bindings", "ffi", "code-generation"]
-categories = ["external-ffi-bindings"]
+categories = ["external-ffi-bindings", "development-tools::ffi"]
 license = "BSD-3-Clause"
 name = "bindgen"
 readme = "README.md"

README.md

@@ -87,6 +87,8 @@ Those instructions list optional steps. For bindgen:
 
 ### Library usage with `build.rs`
 
+💡 This is the recommended way to use `bindgen`. 💡
+
 #### `build.rs` Tutorial
 
 [Here is a step-by-step tutorial for generating FFI bindings to the `bzip2` C library.][tutorial]
@@ -153,11 +155,23 @@ There are a few options documented when running `./bindgen --help`.
 
 ### C++
 
-This fork of rust-bindgen can handle a number of C++ features.
+`bindgen` can handle most C++ features, but not all of them (C++ is hard!)
+
+Notable C++ features that are unsupported or only partially supported:
+
+* Partial template specialization
+* Traits templates
+* SFINAE
+* Instantiating new template specializations
 
 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.
 
+You must use whitelisting when working with C++ to avoid pulling in all of the
+`std::*` types, some of which `bindgen` cannot handle. Additionally, you may
+want to blacklist other types that `bindgen` stumbles on, or make `bindgen`
+treat certain types as opaque.
+
 ### Annotations
 
 The translation of classes, structs, enums, and typedefs can be adjusted using