Add some doc comments.
diff --git a/src/attr.rs b/src/attr.rs
index afa611e..443daa5 100644
--- a/src/attr.rs
+++ b/src/attr.rs
@@ -21,7 +21,10 @@
/// distinguished for pretty-printing.
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
pub enum AttrStyle {
+ /// Attribute of the form `#![...]`.
Outer,
+
+ /// Attribute of the form `#[...]`.
Inner,
}
@@ -34,17 +37,23 @@
///
/// E.g. `test` as in `#[test]`
Word(Ident),
+
/// List meta item.
///
/// E.g. `derive(..)` as in `#[derive(..)]`
List(Ident, Vec<NestedMetaItem>),
- /// Name value meta item.
+
+ /// Name-value meta item.
///
/// E.g. `feature = "foo"` as in `#[feature = "foo"]`
NameValue(Ident, Lit),
}
impl MetaItem {
+ /// Name of the item.
+ ///
+ /// E.g. `test` as in `#[test]`, `derive` as in `#[derive(..)]`, and
+ /// `feature` as in `#[feature = "foo"]`.
pub fn name(&self) -> &str {
match *self {
MetaItem::Word(ref name) |
@@ -59,11 +68,14 @@
/// E.g. the '..' in `#[name(..)]`.
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub enum NestedMetaItem {
- /// A full MetaItem, for recursive meta items.
- MetaItem(MetaItem),
- /// A literal.
+ /// A full `MetaItem`.
///
- /// E.g. "foo", 64, true
+ /// E.g. `Copy` in `#[derive(Copy)]` would be a `MetaItem::Word(Ident::from("Copy"))`.
+ MetaItem(MetaItem),
+
+ /// A Rust literal.
+ ///
+ /// E.g. `"name"` in `#[rename("name")]`.
Literal(Lit),
}
diff --git a/src/constant.rs b/src/constant.rs
index 145729d..ad0d325 100644
--- a/src/constant.rs
+++ b/src/constant.rs
@@ -7,21 +7,29 @@
/// The first field resolves to the function itself,
/// and the second field is the list of arguments
Call(Box<ConstExpr>, Vec<ConstExpr>),
+
/// A binary operation (For example: `a + b`, `a * b`)
Binary(BinOp, Box<ConstExpr>, Box<ConstExpr>),
+
/// A unary operation (For example: `!x`, `*x`)
Unary(UnOp, Box<ConstExpr>),
+
/// A literal (For example: `1`, `"foo"`)
Lit(Lit),
+
/// A cast (`foo as f64`)
Cast(Box<ConstExpr>, Box<Ty>),
+
/// Variable reference, possibly containing `::` and/or type
/// parameters, e.g. foo::bar::<baz>.
Path(Path),
+
/// An indexing operation (`foo[2]`)
Index(Box<ConstExpr>, Box<ConstExpr>),
+
/// No-op: used solely so we can pretty-print faithfully
Paren(Box<ConstExpr>),
+
/// If compiling with full support for expression syntax, any expression is
/// allowed
Other(Other),
diff --git a/src/data.rs b/src/data.rs
index c1ae79c..f21bfd8 100644
--- a/src/data.rs
+++ b/src/data.rs
@@ -1,22 +1,36 @@
use super::*;
+/// An enum variant.
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub struct Variant {
+ /// Name of the variant.
pub ident: Ident,
+
+ /// Attributes tagged on the variant.
pub attrs: Vec<Attribute>,
+
+ /// Type of variant.
pub data: VariantData,
+
/// Explicit discriminant, e.g. `Foo = 1`
pub discriminant: Option<ConstExpr>,
}
+/// Data stored within an enum variant or struct.
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub enum VariantData {
+ /// Struct variant, e.g. `Point { x: f64, y: f64 }`.
Struct(Vec<Field>),
+
+ /// Tuple variant, e.g. `Some(T)`.
Tuple(Vec<Field>),
+
+ /// Unit variant, e.g. `None`.
Unit,
}
impl VariantData {
+ /// Slice containing the fields stored in the variant.
pub fn fields(&self) -> &[Field] {
match *self {
VariantData::Struct(ref fields) |
@@ -25,6 +39,7 @@
}
}
+ /// Mutable slice containing the fields stored in the variant.
pub fn fields_mut(&mut self) -> &mut [Field] {
match *self {
VariantData::Struct(ref mut fields) |
@@ -34,19 +49,38 @@
}
}
+/// A field of a struct or enum variant.
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub struct Field {
+ /// Name of the field, if any.
+ ///
+ /// Fields of tuple structs have no names.
pub ident: Option<Ident>,
+
+ /// Visibility of the field.
pub vis: Visibility,
+
+ /// Attributes tagged on the field.
pub attrs: Vec<Attribute>,
+
+ /// Type of the field.
pub ty: Ty,
}
+
+/// Visibility level of an item.
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub enum Visibility {
+ /// Public, i.e. `pub`.
Public,
+
+ /// Crate-visible, i.e. `pub(crate)`.
Crate,
+
+ /// Restricted, e.g. `pub(some::module)`.
Restricted(Box<Path>),
+
+ /// Inherited, i.e. private.
Inherited,
}
diff --git a/src/derive.rs b/src/derive.rs
index 20b710b..306c352 100644
--- a/src/derive.rs
+++ b/src/derive.rs
@@ -1,17 +1,31 @@
use super::*;
+/// Struct or enum sent to a `proc_macro_derive` macro.
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub struct DeriveInput {
+ /// Name of the struct or enum.
pub ident: Ident,
+
+ /// Visibility of the struct or enum.
pub vis: Visibility,
+
+ /// Attributes tagged on the whole struct or enum.
pub attrs: Vec<Attribute>,
+
+ /// Generics required to complete the definition.
pub generics: Generics,
+
+ /// Data within the struct or enum.
pub body: Body,
}
+/// Body of a derived struct or enum.
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub enum Body {
+ /// It's an enum.
Enum(Vec<Variant>),
+
+ /// It's a struct.
Struct(VariantData),
}
diff --git a/src/expr.rs b/src/expr.rs
index d747625..cde988e 100644
--- a/src/expr.rs
+++ b/src/expr.rs
@@ -1,8 +1,12 @@
use super::*;
+/// An expression.
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub struct Expr {
+ /// Type of the expression.
pub node: ExprKind,
+
+ /// Attributes tagged on the expression.
pub attrs: Vec<Attribute>,
}
@@ -19,15 +23,21 @@
pub enum ExprKind {
/// A `box x` expression.
Box(Box<Expr>),
+
/// First expr is the place; second expr is the value.
+ ///
+ /// E.g. 'plae <- val'.
InPlace(Box<Expr>, Box<Expr>),
- /// An array (`[a, b, c, d]`)
+
+ /// An array, e.g. `[a, b, c, d]`.
Array(Vec<Expr>),
- /// A function call
+
+ /// A function call.
///
/// The first field resolves to the function itself,
/// and the second field is the list of arguments
Call(Box<Expr>, Vec<Expr>),
+
/// A method call (`x.foo::<Bar, Baz>(a, b, c, d)`)
///
/// The `Ident` is the identifier for the method name.
@@ -41,69 +51,89 @@
/// Thus, `x.foo::<Bar, Baz>(a, b, c, d)` is represented as
/// `ExprKind::MethodCall(foo, [Bar, Baz], [x, a, b, c, d])`.
MethodCall(Ident, Vec<Ty>, Vec<Expr>),
- /// A tuple (`(a, b, c, d)`)
+
+ /// A tuple, e.g. `(a, b, c, d)`.
Tup(Vec<Expr>),
- /// A binary operation (For example: `a + b`, `a * b`)
+
+ /// A binary operation, e.g. `a + b`, `a * b`.
Binary(BinOp, Box<Expr>, Box<Expr>),
- /// A unary operation (For example: `!x`, `*x`)
+
+ /// A unary operation, e.g. `!x`, `*x`.
Unary(UnOp, Box<Expr>),
- /// A literal (For example: `1`, `"foo"`)
+
+ /// A literal, e.g. `1`, `"foo"`.
Lit(Lit),
- /// A cast (`foo as f64`)
+
+ /// A cast, e.g. `foo as f64`.
Cast(Box<Expr>, Box<Ty>),
- /// Type ascription (`foo: f64`)
+
+ /// A type ascription, e.g. `foo: f64`.
Type(Box<Expr>, Box<Ty>),
+
/// An `if` block, with an optional else block
///
- /// `if expr { block } else { expr }`
+ /// E.g., `if expr { block } else { expr }`
If(Box<Expr>, Block, Option<Box<Expr>>),
+
/// An `if let` expression with an optional else block
///
- /// `if let pat = expr { block } else { expr }`
+ /// E.g., `if let pat = expr { block } else { expr }`
///
/// This is desugared to a `match` expression.
IfLet(Box<Pat>, Box<Expr>, Block, Option<Box<Expr>>),
+
/// A while loop, with an optional label
///
- /// `'label: while expr { block }`
+ /// E.g., `'label: while expr { block }`
While(Box<Expr>, Block, Option<Ident>),
- /// A while-let loop, with an optional label
+
+ /// A while-let loop, with an optional label.
///
- /// `'label: while let pat = expr { block }`
+ /// E.g., `'label: while let pat = expr { block }`
///
/// This is desugared to a combination of `loop` and `match` expressions.
WhileLet(Box<Pat>, Box<Expr>, Block, Option<Ident>),
- /// A for loop, with an optional label
+
+ /// A for loop, with an optional label.
///
- /// `'label: for pat in expr { block }`
+ /// E.g., `'label: for pat in expr { block }`
///
/// This is desugared to a combination of `loop` and `match` expressions.
ForLoop(Box<Pat>, Box<Expr>, Block, Option<Ident>),
- /// Conditionless loop (can be exited with break, continue, or return)
+
+ /// Conditionless loop with an optional label.
///
- /// `'label: loop { block }`
+ /// E.g. `'label: loop { block }`
Loop(Block, Option<Ident>),
+
/// A `match` block.
Match(Box<Expr>, Vec<Arm>),
+
/// A closure (for example, `move |a, b, c| a + b + c`)
Closure(CaptureBy, Box<FnDecl>, Box<Expr>),
+
/// A block (`{ ... }` or `unsafe { ... }`)
Block(Unsafety, Block),
/// An assignment (`a = foo()`)
Assign(Box<Expr>, Box<Expr>),
+
/// An assignment with an operator
///
/// For example, `a += 1`.
AssignOp(BinOp, Box<Expr>, Box<Expr>),
+
/// Access of a named struct field (`obj.foo`)
Field(Box<Expr>, Ident),
+
/// Access of an unnamed field of a struct or tuple-struct
///
/// For example, `foo.0`.
TupField(Box<Expr>, usize),
+
/// An indexing operation (`foo[2]`)
Index(Box<Expr>, Box<Expr>),
+
/// A range (`1..2`, `1..`, `..2`, `1...2`, `1...`, `...2`)
Range(Option<Box<Expr>>, Option<Box<Expr>>, RangeLimits),
@@ -116,10 +146,13 @@
/// A referencing operation (`&a` or `&mut a`)
AddrOf(Mutability, Box<Expr>),
+
/// A `break`, with an optional label to break, and an optional expression
Break(Option<Ident>, Option<Box<Expr>>),
+
/// A `continue`, with an optional label
Continue(Option<Ident>),
+
/// A `return`, with an optional value to be returned
Ret(Option<Box<Expr>>),
@@ -145,11 +178,20 @@
Try(Box<Expr>),
}
+/// A field-value pair in a struct literal.
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub struct FieldValue {
+ /// Name of the field.
pub ident: Ident,
+
+ /// Value of the field.
pub expr: Expr,
+
+ /// Whether this is a shorthand field, e.g. `Struct { x }`
+ /// instead of `Struct { x: x }`.
pub is_shorthand: bool,
+
+ /// Attributes tagged on the field.
pub attrs: Vec<Attribute>,
}
@@ -162,6 +204,7 @@
pub stmts: Vec<Stmt>,
}
+/// A statement, usually ending in a semicolon.
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub enum Stmt {
/// A local (let) binding.
@@ -170,21 +213,26 @@
/// An item definition.
Item(Box<Item>),
- /// Expr without trailing semi-colon.
+ /// Expr without trailing semicolon.
Expr(Box<Expr>),
+ /// Expression with trailing semicolon;
Semi(Box<Expr>),
+ /// Macro invocation.
Mac(Box<(Mac, MacStmtStyle, Vec<Attribute>)>),
}
+/// How a macro was invoked.
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
pub enum MacStmtStyle {
/// The macro statement had a trailing semicolon, e.g. `foo! { ... };`
/// `foo!(...);`, `foo![...];`
Semicolon,
+
/// The macro statement had braces; e.g. foo! { ... }
Braces,
+
/// The macro statement had parentheses or brackets and no semicolon; e.g.
/// `foo!(...)`. All of these will end up being converted into macro
/// expressions.
@@ -196,6 +244,7 @@
pub struct Local {
pub pat: Box<Pat>,
pub ty: Option<Box<Ty>>,
+
/// Initializer expression to set the value, if any
pub init: Option<Box<Expr>>,
pub attrs: Vec<Attribute>,