From 7130fb30f3eb37afa9d9397ae4d3f9432024e9b7 Mon Sep 17 00:00:00 2001
From: Nick Fitzgerald <fitzgen@gmail.com>
Date: Thu, 27 Oct 2016 16:21:44 -0700
Subject: [PATCH] Document the `parse` module

---
 src/ir/item.rs |  2 +-
 src/lib.rs     |  2 +-
 src/parse.rs   | 55 +++++++++++++++++++++++++++++++++++++++++---------
 3 files changed, 48 insertions(+), 11 deletions(-)

diff --git a/src/ir/item.rs b/src/ir/item.rs
index 8ec4e78abe..c68ed5f748 100644
--- a/src/ir/item.rs
+++ b/src/ir/item.rs
@@ -695,7 +695,7 @@ impl ClangItemParser for Item {
     }
 
     /// Parse a C++ type. If we find a reference to a type that has not been
-    /// defined yet, use UnresolvedTypeRef as a placeholder.
+    /// 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
diff --git a/src/lib.rs b/src/lib.rs
index 76862721e5..1ee2418766 100755
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -55,7 +55,7 @@ macro_rules! doc_mod {
 mod clangll;
 doc_mod!(clang);
 doc_mod!(ir);
-mod parse;
+doc_mod!(parse);
 mod regex_set;
 
 mod codegen {
diff --git a/src/parse.rs b/src/parse.rs
index c71f4c52b5..1f5566437f 100644
--- a/src/parse.rs
+++ b/src/parse.rs
@@ -1,53 +1,90 @@
+//! Common traits and types related to parsing our IR from Clang cursors.
+
 use clang;
 use ir::ty::TypeKind;
 use ir::item::ItemId;
 use ir::context::BindgenContext;
 
+/// Not so much an error in the traditional sense, but a control flow message
+/// when walking over Clang's AST with a cursor.
 #[derive(Debug)]
 pub enum ParseError {
+    /// Recurse down the current AST node's children.
     Recurse,
+    /// Continue on to the next sibling AST node, or back up to the parent's
+    /// siblings if we've exhausted all of this node's siblings (and so on).
     Continue,
 }
 
+/// The result of parsing a Clang AST node.
 #[derive(Debug)]
 pub enum ParseResult<T> {
+    /// We've already resolved this item before, here is the extant `ItemId` for
+    /// it.
     AlreadyResolved(ItemId),
+
+    /// This is a newly parsed item. If the cursor is `Some`, it points to the
+    /// AST node where the new `T` was declared.
     New(T, Option<clang::Cursor>),
 }
 
+/// An intermediate representation "sub-item" (i.e. one of the types contained
+/// inside an `ItemKind` variant) that can be parsed from a Clang cursor.
 pub trait ClangSubItemParser : Sized {
+    /// Attempt to parse this type from the given cursor.
+    ///
     /// The fact that is a reference guarantees it's held by the context, and
     /// allow returning already existing types.
     fn parse(cursor: clang::Cursor, context: &mut BindgenContext) -> Result<ParseResult<Self>, ParseError>;
 }
 
+/// An intermediate representation item that can be parsed from a Clang cursor.
 pub trait ClangItemParser: Sized {
+    /// Parse this item from the given Clang cursor.
     fn parse(cursor: clang::Cursor,
              parent: Option<ItemId>,
              context: &mut BindgenContext) -> Result<ItemId, ParseError>;
+
+    /// Parse this item from the given Clang type.
+    fn from_ty(ty: &clang::Type,
+               location: Option<clang::Cursor>,
+               parent: Option<ItemId>,
+               ctx: &mut BindgenContext) -> Result<ItemId, ParseError>;
+
+    /// Identical to `from_ty`, but use the given `id` as the `ItemId` for the
+    /// newly parsed item.
+    fn from_ty_with_id(id: ItemId,
+                       ty: &clang::Type,
+                       location: Option<clang::Cursor>,
+                       parent: Option<ItemId>,
+                       ctx: &mut BindgenContext) -> Result<ItemId, ParseError>;
+
+    /// Parse this item from the given Clang type, or if we haven't resolved all
+    /// the other items this one depends on, an unresolved reference.
     fn from_ty_or_ref(ty: clang::Type,
                       location: Option<clang::Cursor>,
                       parent_id: Option<ItemId>,
                       context: &mut BindgenContext) -> ItemId;
+
+    /// Identical to `from_ty_or_ref`, but use the given `potential_id` as the
+    /// `ItemId` for the newly parsed item.
     fn from_ty_or_ref_with_id(potential_id: ItemId,
                               ty: clang::Type,
                               location: Option<clang::Cursor>,
                               parent_id: Option<ItemId>,
                               context: &mut BindgenContext) -> ItemId;
-    fn from_ty_with_id(id: ItemId,
-                       ty: &clang::Type,
-                       location: Option<clang::Cursor>,
-                       parent: Option<ItemId>,
-                       ctx: &mut BindgenContext) -> Result<ItemId, ParseError>;
-    fn from_ty(ty: &clang::Type,
-               location: Option<clang::Cursor>,
-               parent: Option<ItemId>,
-               ctx: &mut BindgenContext) -> Result<ItemId, ParseError>;
+
+    /// Create a named template type.
     fn named_type<S>(name: S, default: Option<ItemId>, parent: ItemId,
                      context: &mut BindgenContext) -> ItemId
         where S: Into<String>;
+
+    /// Identical to `named_type`, but use `id` as the resulting item's
+    /// `ItemId`.
     fn named_type_with_id<S>(id: ItemId, name: S, default: Option<ItemId>,
                              parent: ItemId, context: &mut BindgenContext) -> ItemId
         where S: Into<String>;
+
+    /// Create a builtin type.
     fn builtin_type(kind: TypeKind, is_const: bool, context: &mut BindgenContext) -> ItemId;
 }