squash! use_as -> use_instead_of, and doc fixes.

Author: emilio

src/codegen/mod.rs

@@ -206,6 +206,8 @@ impl ArrayTyBuilder {
     }
 }
 
+/// Generates a proper type for a field or type with a given `Layout`, that is,
+/// a type with the correct size and alignment restrictions.
 struct BlobTyBuilder {
     layout: Layout,
 }
@@ -1154,8 +1156,8 @@ impl MethodCodegen for Method {
             constness: ast::Constness::NotConst,
         };
 
-        // TODO: This needs to be kept in sync, so we'd be better unifying this,
-        // I guess.
+        // TODO: We need to keep in sync the argument names, so we should unify
+        // this with the other loop that decides them.
         let mut unnamed_arguments = 0;
         let mut exprs = signature.argument_types().iter().map(|&(ref name, _ty)| {
             let arg_name = match *name {

src/ir/annotations.rs

@@ -18,7 +18,7 @@ pub struct Annotations {
     hide: bool,
     /// Whether this type should be replaced by another. The name must be the
     /// canonical name that that type would get.
-    use_as: Option<String>,
+    use_instead_of: Option<String>,
     /// Manually disable deriving copy/clone on this type. Only applies to
     /// struct or union types.
     disallow_copy: bool,
@@ -44,7 +44,7 @@ impl Default for Annotations {
         Annotations {
             opaque: false,
             hide: false,
-            use_as: None,
+            use_instead_of: None,
             disallow_copy: false,
             private_fields: None,
             accessor_kind: None
@@ -73,8 +73,30 @@ impl Annotations {
         self.opaque
     }
 
-    pub fn use_as(&self) -> Option<&str> {
-        self.use_as.as_ref().map(|s| &**s)
+    /// For a given type, indicates the type it should replace.
+    ///
+    /// For example, in the following code:
+    ///
+    /// ```cpp
+    ///
+    /// /** <div rustbindgen replaces="Bar"></div> */
+    /// struct Foo { int x; };
+    ///
+    /// struct Bar { char foo; };
+    /// ```
+    ///
+    /// the generated code would look something like:
+    ///
+    /// ```rust
+    /// /** <div rustbindgen replaces="Bar"></div> */
+    /// struct Bar {
+    ///     int x;
+    /// };
+    /// ```
+    ///
+    /// That is, code for `Foo` is used to generate `Bar`.
+    pub fn use_instead_of(&self) -> Option<&str> {
+        self.use_instead_of.as_ref().map(|s| &**s)
     }
 
     pub fn disallow_copy(&self) -> bool {
@@ -103,7 +125,7 @@ impl Annotations {
                     "opaque" => self.opaque = true,
                     "hide" => self.hide = true,
                     "nocopy" => self.disallow_copy = true,
-                    "replaces" => self.use_as = Some(value),
+                    "replaces" => self.use_instead_of = Some(value),
                     "private" => self.private_fields = Some(value != "false"),
                     "accessor"
                         => self.accessor_kind = Some(parse_accessor(&value)),

src/ir/item.rs

@@ -248,7 +248,7 @@ impl Item {
             ctx.opaque_by_name(&self.real_canonical_name(ctx, false))
     }
 
-    /// Get the canonical name without taking into account the use_as
+    /// Get the canonical name without taking into account the replaces
     /// annotation.
     fn real_canonical_name(&self, ctx: &BindgenContext, count_namespaces: bool) -> String {
         let base_name = match *self.kind() {
@@ -496,7 +496,7 @@ impl ClangItemParser for Item {
             Annotations::new(&decl)
                       .or_else(|| location.as_ref().and_then(|l| Annotations::new(l)));
 
-        if let Some(ref replaced) = annotations.as_ref().and_then(|a| a.use_as()) {
+        if let Some(ref replaced) = annotations.as_ref().and_then(|a| a.use_instead_of()) {
             context.replace(replaced, id);
         }
 
@@ -635,7 +635,7 @@ impl ItemCanonicalName for Item {
     fn canonical_name(&self, ctx: &BindgenContext) -> String {
         debug_assert!(ctx.in_codegen_phase(),
                       "You're not supposed to call this yet");
-        if let Some(other_canon_type) = self.annotations.use_as() {
+        if let Some(other_canon_type) = self.annotations.use_instead_of() {
             return other_canon_type.to_owned();
         }
         self.real_canonical_name(ctx, ctx.options().enable_cxx_namespaces)