Skip to content

Improve syntax::ast::* type docs (examples, etc) #34449

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Improve syntax::ast::* type docs (examples, etc) #34449

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
171 changes: 135 additions & 36 deletions src/libsyntax/ast.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,16 +171,19 @@ impl fmt::Debug for Lifetime {
}
}

/// A lifetime definition, eg `'a: 'b+'c+'d`
/// A lifetime definition, e.g. `'a: 'b+'c+'d`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct LifetimeDef {
pub lifetime: Lifetime,
pub bounds: Vec<Lifetime>
}

/// A "Path" is essentially Rust's notion of a name; for instance:
/// std::cmp::PartialEq . It's represented as a sequence of identifiers,
/// A "Path" is essentially Rust's notion of a name.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add an empty line here (well, one that starts with /// actually), so rustdoc can pick this first sentence for use as a short description?

///
/// It's represented as a sequence of identifiers,
/// along with a bunch of supporting information.
///
/// E.g. `std::cmp::PartialEq`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash)]
pub struct Path {
pub span: Span,
Expand Down Expand Up @@ -220,8 +223,9 @@ impl Path {
}
}

/// A segment of a path: an identifier, an optional lifetime, and a set of
/// types.
/// A segment of a path: an identifier, an optional lifetime, and a set of types.
///
/// E.g. `std`, `String` or `Box<T>`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct PathSegment {
/// The identifier portion of this path segment.
Expand All @@ -235,6 +239,9 @@ pub struct PathSegment {
pub parameters: PathParameters,
}

/// Parameters of a path segment.
///
/// E.g. `<A, B>` as in `Foo<A, B>` or `(A, B)` as in `Foo(A, B)`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub enum PathParameters {
/// The `<'a, A,B,C>` in `foo::bar::baz::<'a, A,B,C>`
Expand Down Expand Up @@ -322,7 +329,8 @@ pub struct AngleBracketedParameterData {
/// The type parameters for this path segment, if present.
pub types: P<[P<Ty>]>,
/// Bindings (equality constraints) on associated types, if present.
/// e.g., `Foo<A=Bar>`.
///
/// E.g., `Foo<A=Bar>`.
pub bindings: P<[TypeBinding]>,
}

Expand Down Expand Up @@ -447,7 +455,9 @@ pub enum WherePredicate {
EqPredicate(WhereEqPredicate),
}

/// A type bound, e.g. `for<'c> Foo: Send+Clone+'c`
/// A type bound.
///
/// E.g. `for<'c> Foo: Send+Clone+'c`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct WhereBoundPredicate {
pub span: Span,
Expand All @@ -459,15 +469,19 @@ pub struct WhereBoundPredicate {
pub bounds: TyParamBounds,
}

/// A lifetime predicate, e.g. `'a: 'b+'c`
/// A lifetime predicate.
///
/// E.g. `'a: 'b+'c`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct WhereRegionPredicate {
pub span: Span,
pub lifetime: Lifetime,
pub bounds: Vec<Lifetime>,
}

/// An equality predicate (unsupported), e.g. `T=int`
/// An equality predicate (unsupported).
///
/// E.g. `T=int`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct WhereEqPredicate {
pub id: NodeId,
Expand All @@ -489,12 +503,27 @@ pub struct Crate {
pub exported_macros: Vec<MacroDef>,
}

/// A spanned compile-time attribute item.
///
/// E.g. `#[test]`, `#[derive(..)]` or `#[feature = "foo"]`
pub type MetaItem = Spanned<MetaItemKind>;

/// A compile-time attribute item.
///
/// E.g. `#[test]`, `#[derive(..)]` or `#[feature = "foo"]`
#[derive(Clone, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub enum MetaItemKind {
/// Word meta item.
///
/// E.g. `test` as in `#[test]`
Word(InternedString),
/// List meta item.
///
/// E.g. `derive(..)` as in `#[derive(..)]`
List(InternedString, Vec<P<MetaItem>>),
/// Name value meta item.
///
/// E.g. `feature = "foo"` as in `#[feature = "foo"]`
NameValue(InternedString, Lit),
}

Expand Down Expand Up @@ -524,6 +553,9 @@ impl PartialEq for MetaItemKind {
}
}

/// A Block (`{ .. }`).
///
/// E.g. `{ .. }` as in `fn foo() { .. }`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct Block {
/// Statements in a block
Expand Down Expand Up @@ -876,7 +908,16 @@ impl Decl {
}
}

/// represents one arm of a 'match'
/// An arm of a 'match'.
///
/// E.g. `0...10 => { println!("match!") }` as in
///
/// ```rust,ignore
/// match n {
/// 0...10 => { println!("match!") },
/// // ..
/// }
/// ```
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct Arm {
pub attrs: Vec<Attribute>,
Expand Down Expand Up @@ -1033,7 +1074,7 @@ pub enum ExprKind {
/// parameters, e.g. foo::bar::<baz>.
///
/// Optionally "qualified",
/// e.g. `<Vec<T> as SomeTrait>::SomeType`.
/// E.g. `<Vec<T> as SomeTrait>::SomeType`.
Path(Option<QSelf>, Path),

/// A referencing operation (`&a` or `&mut a`)
Expand Down Expand Up @@ -1075,7 +1116,7 @@ pub enum ExprKind {
/// separately. `position` represents the index of the associated
/// item qualified with this Self type.
///
/// ```ignore
/// ```rust,ignore
/// <Vec<T> as a::b::Trait>::AssociatedItem
/// ^~~~~ ~~~~~~~~~~~~~~^
/// ty position = 3
Expand Down Expand Up @@ -1319,6 +1360,9 @@ pub enum LitIntType {
Unsuffixed,
}

/// Literal kind.
///
/// E.g. `"foo"`, `42`, `12.34` or `bool`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub enum LitKind {
/// A string literal (`"foo"`)
Expand Down Expand Up @@ -1586,8 +1630,8 @@ pub struct BareFnTy {
pub decl: P<FnDecl>
}

#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
/// The different kinds of types recognized by the compiler
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub enum TyKind {
Vec(P<Ty>),
/// A fixed length array (`[T; n]`)
Expand Down Expand Up @@ -1622,12 +1666,18 @@ pub enum TyKind {
Mac(Mac),
}

/// Inline assembly dialect.
///
/// E.g. `"intel"` as in `asm!("mov eax, 2" : "={eax}"(result) : : : "intel")``
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug, Copy)]
pub enum AsmDialect {
Att,
Intel,
}

/// Inline assembly.
///
/// E.g. `"={eax}"(result)` as in `asm!("mov eax, 2" : "={eax}"(result) : : : "intel")``
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct InlineAsmOutput {
pub constraint: InternedString,
Expand All @@ -1636,6 +1686,9 @@ pub struct InlineAsmOutput {
pub is_indirect: bool,
}

/// Inline assembly.
///
/// E.g. `asm!("NOP");`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct InlineAsm {
pub asm: InternedString,
Expand All @@ -1649,7 +1702,9 @@ pub struct InlineAsm {
pub expn_id: ExpnId,
}

/// represents an argument in a function header
/// An argument in a function header.
///
/// E.g. `bar: usize` as in `fn foo(bar: usize)`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct Arg {
pub ty: P<Ty>,
Expand All @@ -1658,6 +1713,8 @@ pub struct Arg {
}

/// Alternative representation for `Arg`s describing `self` parameter of methods.
///
/// E.g. `&mut self` as in `fn foo(&mut self)`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub enum SelfKind {
/// `self`, `mut self`
Expand Down Expand Up @@ -1724,7 +1781,9 @@ impl Arg {
}
}

/// Represents the header (not the body) of a function declaration
/// Header (not the body) of a function declaration.
///
/// E.g. `fn foo(bar: baz)`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct FnDecl {
pub inputs: Vec<Arg>,
Expand Down Expand Up @@ -1811,6 +1870,9 @@ impl FunctionRetTy {
}
}

/// Module declaration.
///
/// E.g. `mod foo;` or `mod foo { .. }`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct Mod {
/// A span from the first token past `{` to the last token until `}`.
Expand All @@ -1820,6 +1882,9 @@ pub struct Mod {
pub items: Vec<P<Item>>,
}

/// Foreign module declaration.
///
/// E.g. `extern { .. }` or `extern C { .. }`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct ForeignMod {
pub abi: Abi,
Expand All @@ -1836,7 +1901,7 @@ pub struct Variant_ {
pub name: Ident,
pub attrs: Vec<Attribute>,
pub data: VariantData,
/// Explicit discriminant, eg `Foo = 1`
/// Explicit discriminant, e.g. `Foo = 1`
pub disr_expr: Option<P<Expr>>,
}

Expand All @@ -1846,12 +1911,12 @@ pub type Variant = Spanned<Variant_>;
pub enum PathListItemKind {
Ident {
name: Ident,
/// renamed in list, eg `use foo::{bar as baz};`
/// renamed in list, e.g. `use foo::{bar as baz};`
rename: Option<Ident>,
id: NodeId
},
Mod {
/// renamed in list, eg `use foo::{self as baz};`
/// renamed in list, e.g. `use foo::{self as baz};`
rename: Option<Ident>,
id: NodeId
}
Expand Down Expand Up @@ -1964,6 +2029,9 @@ pub enum Visibility {
Inherited,
}

/// Field of a struct.
///
/// E.g. `bar: usize` as in `struct Foo { bar: usize }`
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub struct StructField {
pub span: Span,
Expand All @@ -1987,8 +2055,17 @@ pub struct StructField {
/// Id of the whole struct lives in `Item`.
#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub enum VariantData {
/// Struct variant.
///
/// E.g. `Bar { .. }` as in `enum Foo { Bar { .. } }`
Struct(Vec<StructField>, NodeId),
/// Tuple variant.
///
/// E.g. `Bar(..)` as in `enum Foo { Bar(..) }`
Tuple(Vec<StructField>, NodeId),
/// Unit variant.
///
/// E.g. `Bar = ..` as in `enum Foo { Bar = .. }`
Unit(NodeId),
}

Expand Down Expand Up @@ -2040,44 +2117,66 @@ impl Item {

#[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)]
pub enum ItemKind {
/// An`extern crate` item, with optional original crate name,
/// An`extern crate` item, with optional original crate name.
///
/// e.g. `extern crate foo` or `extern crate foo_bar as foo`
/// E.g. `extern crate foo` or `extern crate foo_bar as foo`
ExternCrate(Option<Name>),
/// A `use` or `pub use` item
/// A use declaration (`use` or `pub use`) item.
///
/// E.g. `use foo;`, `use foo::bar;` or `use foo::bar as FooBar;`
Use(P<ViewPath>),

/// A `static` item
/// A static item (`static` or `pub static`).
///
/// E.g. `static FOO: i32 = 42;` or `static FOO: &'static str = "bar";`
Static(P<Ty>, Mutability, P<Expr>),
/// A `const` item
/// A constant item (`const` or `pub const`).
///
/// E.g. `const FOO: i32 = 42;`
Const(P<Ty>, P<Expr>),
/// A function declaration
/// A function declaration (`fn` or `pub fn`).
///
/// E.g. `fn foo(bar: usize) -> usize { .. }`
Fn(P<FnDecl>, Unsafety, Constness, Abi, Generics, P<Block>),
/// A module
/// A module declaration (`mod` or `pub mod`).
///
/// E.g. `mod foo;` or `mod foo { .. }`
Mod(Mod),
/// An external module
/// An external module (`extern` or `pub extern`).
///
/// E.g. `extern {}` or `extern "C" {}`
ForeignMod(ForeignMod),
/// A type alias, e.g. `type Foo = Bar<u8>`
/// A type alias (`type` or `pub type`).
///
/// E.g. `type Foo = Bar<u8>;`
Ty(P<Ty>, Generics),
/// An enum definition, e.g. `enum Foo<A, B> {C<A>, D<B>}`
/// An enum definition (`enum` or `pub enum`).
///
/// E.g. `enum Foo<A, B> { C<A>, D<B> }`
Enum(EnumDef, Generics),
/// A struct definition, e.g. `struct Foo<A> {x: A}`
/// A struct definition (`struct` or `pub struct`).
///
/// E.g. `struct Foo<A> { x: A }`
Struct(VariantData, Generics),
/// Represents a Trait Declaration
/// A Trait declaration (`trait` or `pub trait`).
///
/// E.g. `trait Foo { .. }` or `trait Foo<T> { .. }`
Trait(Unsafety, Generics, TyParamBounds, Vec<TraitItem>),

// Default trait implementations
// Default trait implementation.
///
// `impl Trait for .. {}`
/// E.g. `impl Trait for .. {}` or `impl<T> Trait<T> for .. {}`
DefaultImpl(Unsafety, TraitRef),
/// An implementation, eg `impl<A> Trait for Foo { .. }`
/// An implementation.
///
/// E.g. `impl<A> Foo<A> { .. }` or `impl<A> Trait for Foo<A> { .. }`
Impl(Unsafety,
ImplPolarity,
Generics,
Option<TraitRef>, // (optional) trait this impl implements
P<Ty>, // self
Vec<ImplItem>),
/// A macro invocation (which includes macro definition)
/// A macro invocation (which includes macro definition).
///
/// E.g. `macro_rules! foo { .. }` or `foo!(..)`
Mac(Mac),
}

Expand Down