ir: Nitpicks of the last docs review that I forgot to push.

I forgot to push when I r=fitzgen in #99.

Author: emilio

src/ir/item.rs

@@ -82,10 +82,10 @@ impl ItemCanonicalPath for ItemId {
 /// module, a type, a function, or a variable (see `ItemKind` for more
 /// information).
 ///
-/// Items form a tree, and each item only stores the id of the parent.
+/// Items form a graph, and each item only stores the id of the parent.
 ///
-/// The root of this tree is the "root module", a meta-item used to hold all the
-/// top-level items.
+/// The entry-point of this graph is the "root module", a meta-item used to hold
+/// all the top-level items.
 ///
 /// An item may have a comment, and annotations (see the `annotations` module).
 ///
@@ -163,8 +163,8 @@ impl Item {
     /// they aren't.
     ///
     /// This function is used to determine when the codegen phase should call
-    /// `codegen` on an item, since it's assumed that any item that is not
-    /// top-level will be generated by its parent.
+    /// `codegen` on an item, since any item that is not top-level will be
+    /// generated by its parent.
     pub fn is_toplevel(&self, ctx: &BindgenContext) -> bool {
         // FIXME: Workaround for some types falling behind when parsing weird
         // stl classes, for example.
@@ -610,9 +610,8 @@ impl ClangItemParser for Item {
         Self::from_ty_or_ref_with_id(ItemId::next(), ty, location, parent_id, context)
     }
 
-    /// Parse a type, if we know it before hand, or otherwise store it as an
-    /// `UnresolvedTypeRef`, which means something like "a reference to a type
-    /// we still don't know".
+    /// Parse a C++ type. If we find a reference to a type that has not been
+    /// defined yet, use UnresolvedTypeRef as a placeholder.
     ///
     /// This logic is needed to avoid parsing items with the incorrect parent
     /// and it's sort of complex to explain, so I'll just point to

src/ir/mod.rs

@@ -1,5 +1,7 @@
-//! The module where the Intermediate Representation bindgen uses, and the
-//! parsing code that generates it lives.
+//! The ir module defines bindgen's intermediate representation.
+//!
+//! Parsing C/C++ generates the IR, while code generation outputs Rust code from
+//! the IR.
 
 pub mod annotations;
 pub mod comp;

src/ir/ty.rs

@@ -10,9 +10,9 @@ use clang::{self, Cursor};
 
 /// The base representation of a type in bindgen.
 ///
-/// A type has an optional name, that can't be empty, a `layout` (size,
-/// alignment and packedness) if known, a `Kind`, which determines which kind of
-/// type it is, and whether the type is const.
+/// A type has an optional name, which if present cannot be empty, a `layout`
+/// (size, alignment and packedness) if known, a `Kind`, which determines which
+/// kind of type it is, and whether the type is const.
 #[derive(Debug)]
 pub struct Type {
     /// The name of the type, or None if it was an unnamed struct or union.