diff options
Diffstat (limited to 'src/libsyntax')
| -rw-r--r-- | src/libsyntax/ext/deriving/generic/mod.rs | 285 |
1 files changed, 129 insertions, 156 deletions
diff --git a/src/libsyntax/ext/deriving/generic/mod.rs b/src/libsyntax/ext/deriving/generic/mod.rs index 142adc9b721..10c045b811a 100644 --- a/src/libsyntax/ext/deriving/generic/mod.rs +++ b/src/libsyntax/ext/deriving/generic/mod.rs @@ -101,32 +101,32 @@ //! //! When generating the `expr` for the `A` impl, the `SubstructureFields` is //! -//! ~~~text +//! ```{.text} //! Struct(~[FieldInfo { //! span: <span of x> //! name: Some(<ident of x>), //! self_: <expr for &self.x>, //! other: ~[<expr for &other.x] //! }]) -//! ~~~ +//! ``` //! //! For the `B` impl, called with `B(a)` and `B(b)`, //! -//! ~~~text +//! ```{.text} //! Struct(~[FieldInfo { //! span: <span of `int`>, //! name: None, //! <expr for &a> //! ~[<expr for &b>] //! }]) -//! ~~~ +//! ``` //! //! ## Enums //! //! When generating the `expr` for a call with `self == C0(a)` and `other //! == C0(b)`, the SubstructureFields is //! -//! ~~~text +//! ```{.text} //! EnumMatching(0, <ast::Variant for C0>, //! ~[FieldInfo { //! span: <span of int> @@ -134,11 +134,11 @@ //! self_: <expr for &a>, //! other: ~[<expr for &b>] //! }]) -//! ~~~ +//! ``` //! //! For `C1 {x}` and `C1 {x}`, //! -//! ~~~text +//! ```{.text} //! EnumMatching(1, <ast::Variant for C1>, //! ~[FieldInfo { //! span: <span of x> @@ -146,16 +146,16 @@ //! self_: <expr for &self.x>, //! other: ~[<expr for &other.x>] //! }]) -//! ~~~ +//! ``` //! //! For `C0(a)` and `C1 {x}` , //! -//! ~~~text +//! ```{.text} //! EnumNonMatchingCollapsed( //! ~[<ident of self>, <ident of __arg_1>], //! &[<ast::Variant for C0>, <ast::Variant for C1>], //! &[<ident for self index value>, <ident of __arg_1 index value>]) -//! ~~~ +//! ``` //! //! It is the same for when the arguments are flipped to `C1 {x}` and //! `C0(a)`; the only difference is what the values of the identifiers @@ -170,7 +170,7 @@ //! //! A static method on the above would result in, //! -//! ~~~text +//! ```{.text} //! StaticStruct(<ast::StructDef of A>, Named(~[(<ident of x>, <span of x>)])) //! //! StaticStruct(<ast::StructDef of B>, Unnamed(~[<span of x>])) @@ -178,7 +178,7 @@ //! StaticEnum(<ast::EnumDef of C>, ~[(<ident of C0>, <span of C0>, Unnamed(~[<span of int>])), //! (<ident of C1>, <span of C1>, //! Named(~[(<ident of x>, <span of x>)]))]) -//! ~~~ +//! ``` use std::cell::RefCell; use std::vec; @@ -252,7 +252,7 @@ pub struct Substructure<'a> { pub type_ident: Ident, /// ident of the method pub method_ident: Ident, - /// dereferenced access to any Self or Ptr(Self, _) arguments + /// dereferenced access to any `Self` or `Ptr(Self, _)` arguments pub self_args: &'a [P<Expr>], /// verbatim access to any other arguments pub nonself_args: &'a [P<Expr>], @@ -269,61 +269,52 @@ pub struct FieldInfo { /// (specifically, a reference to it). pub self_: P<Expr>, /// The expressions corresponding to references to this field in - /// the other Self arguments. + /// the other `Self` arguments. pub other: Vec<P<Expr>>, } /// Fields for a static method pub enum StaticFields { - /// Tuple structs/enum variants like this + /// Tuple structs/enum variants like this. Unnamed(Vec<Span>), /// Normal structs/struct variants. Named(Vec<(Ident, Span)>), } -/// A summary of the possible sets of fields. See above for details -/// and examples +/// A summary of the possible sets of fields. pub enum SubstructureFields<'a> { Struct(Vec<FieldInfo>), - /** - Matching variants of the enum: variant index, ast::Variant, - fields: the field name is only non-`None` in the case of a struct - variant. - */ + /// Matching variants of the enum: variant index, ast::Variant, + /// fields: the field name is only non-`None` in the case of a struct + /// variant. EnumMatching(uint, &'a ast::Variant, Vec<FieldInfo>), - /** - non-matching variants of the enum, but with all state hidden from - the consequent code. The first component holds Idents for all of - the Self arguments; the second component is a slice of all of the - variants for the enum itself, and the third component is a list of - Idents bound to the variant index values for each of the actual - input Self arguments. - */ + /// Non-matching variants of the enum, but with all state hidden from + /// the consequent code. The first component holds `Ident`s for all of + /// the `Self` arguments; the second component is a slice of all of the + /// variants for the enum itself, and the third component is a list of + /// `Ident`s bound to the variant index values for each of the actual + /// input `Self` arguments. EnumNonMatchingCollapsed(Vec<Ident>, &'a [P<ast::Variant>], &'a [Ident]), - /// A static method where Self is a struct. + /// A static method where `Self` is a struct. StaticStruct(&'a ast::StructDef, StaticFields), - /// A static method where Self is an enum. + /// A static method where `Self` is an enum. StaticEnum(&'a ast::EnumDef, Vec<(Ident, Span, StaticFields)>), } -/** -Combine the values of all the fields together. The last argument is -all the fields of all the structures, see above for details. -*/ +/// Combine the values of all the fields together. The last argument is +/// all the fields of all the structures. pub type CombineSubstructureFunc<'a> = |&mut ExtCtxt, Span, &Substructure|: 'a -> P<Expr>; -/** -Deal with non-matching enum variants. The tuple is a list of -identifiers (one for each Self argument, which could be any of the -variants since they have been collapsed together) and the identifiers -holding the variant index value for each of the Self arguments. The -last argument is all the non-Self args of the method being derived. -*/ +/// Deal with non-matching enum variants. The tuple is a list of +/// identifiers (one for each `Self` argument, which could be any of the +/// variants since they have been collapsed together) and the identifiers +/// holding the variant index value for each of the `Self` arguments. The +/// last argument is all the non-`Self` args of the method being derived. pub type EnumNonMatchCollapsedFunc<'a> = |&mut ExtCtxt, Span, @@ -373,18 +364,14 @@ impl<'a> TraitDef<'a> { })) } - /** - * - * Given that we are deriving a trait `Tr` for a type `T<'a, ..., - * 'z, A, ..., Z>`, creates an impl like: - * - * ```ignore - * impl<'a, ..., 'z, A:Tr B1 B2, ..., Z: Tr B1 B2> Tr for T<A, ..., Z> { ... } - * ``` - * - * where B1, B2, ... are the bounds given by `bounds_paths`.' - * - */ + /// Given that we are deriving a trait `Tr` for a type `T<'a, ..., + /// 'z, A, ..., Z>`, creates an impl like: + /// + /// ```ignore + /// impl<'a, ..., 'z, A:Tr B1 B2, ..., Z: Tr B1 B2> Tr for T<A, ..., Z> { ... } + /// ``` + /// + /// where B1, B2, ... are the bounds given by `bounds_paths`.' fn create_derived_impl(&self, cx: &mut ExtCtxt, type_ident: Ident, @@ -693,27 +680,25 @@ impl<'a> MethodDef<'a> { }) } - /** - ~~~ - #[deriving(PartialEq)] - struct A { x: int, y: int } - - // equivalent to: - impl PartialEq for A { - fn eq(&self, __arg_1: &A) -> bool { - match *self { - A {x: ref __self_0_0, y: ref __self_0_1} => { - match *__arg_1 { - A {x: ref __self_1_0, y: ref __self_1_1} => { - __self_0_0.eq(__self_1_0) && __self_0_1.eq(__self_1_1) - } - } - } - } - } - } - ~~~ - */ + /// ``` + /// #[deriving(PartialEq)] + /// struct A { x: int, y: int } + /// + /// // equivalent to: + /// impl PartialEq for A { + /// fn eq(&self, __arg_1: &A) -> bool { + /// match *self { + /// A {x: ref __self_0_0, y: ref __self_0_1} => { + /// match *__arg_1 { + /// A {x: ref __self_1_0, y: ref __self_1_1} => { + /// __self_0_0.eq(__self_1_0) && __self_0_1.eq(__self_1_1) + /// } + /// } + /// } + /// } + /// } + /// } + /// ``` fn expand_struct_method_body(&self, cx: &mut ExtCtxt, trait_: &TraitDef, @@ -798,37 +783,35 @@ impl<'a> MethodDef<'a> { &StaticStruct(struct_def, summary)) } - /** - ~~~ - #[deriving(PartialEq)] - enum A { - A1, - A2(int) - } - - // is equivalent to - - impl PartialEq for A { - fn eq(&self, __arg_1: &A) -> ::bool { - match (&*self, &*__arg_1) { - (&A1, &A1) => true, - (&A2(ref __self_0), - &A2(ref __arg_1_0)) => (*__self_0).eq(&(*__arg_1_0)), - _ => { - let __self_vi = match *self { A1(..) => 0u, A2(..) => 1u }; - let __arg_1_vi = match *__arg_1 { A1(..) => 0u, A2(..) => 1u }; - false - } - } - } - } - ~~~ - - (Of course `__self_vi` and `__arg_1_vi` are unused for - `PartialEq`, and those subcomputations will hopefully be removed - as their results are unused. The point of `__self_vi` and - `__arg_1_vi` is for `PartialOrd`; see #15503.) - */ + /// ``` + /// #[deriving(PartialEq)] + /// enum A { + /// A1, + /// A2(int) + /// } + /// + /// // is equivalent to + /// + /// impl PartialEq for A { + /// fn eq(&self, __arg_1: &A) -> ::bool { + /// match (&*self, &*__arg_1) { + /// (&A1, &A1) => true, + /// (&A2(ref __self_0), + /// &A2(ref __arg_1_0)) => (*__self_0).eq(&(*__arg_1_0)), + /// _ => { + /// let __self_vi = match *self { A1(..) => 0u, A2(..) => 1u }; + /// let __arg_1_vi = match *__arg_1 { A1(..) => 0u, A2(..) => 1u }; + /// false + /// } + /// } + /// } + /// } + /// ``` + /// + /// (Of course `__self_vi` and `__arg_1_vi` are unused for + /// `PartialEq`, and those subcomputations will hopefully be removed + /// as their results are unused. The point of `__self_vi` and + /// `__arg_1_vi` is for `PartialOrd`; see #15503.) fn expand_enum_method_body(&self, cx: &mut ExtCtxt, trait_: &TraitDef, @@ -842,33 +825,31 @@ impl<'a> MethodDef<'a> { } - /** - Creates a match for a tuple of all `self_args`, where either all - variants match, or it falls into a catch-all for when one variant - does not match. - - There are N + 1 cases because is a case for each of the N - variants where all of the variants match, and one catch-all for - when one does not match. - - The catch-all handler is provided access the variant index values - for each of the self-args, carried in precomputed variables. (Nota - bene: the variant index values are not necessarily the - discriminant values. See issue #15523.) - - ~~~text - match (this, that, ...) { - (Variant1, Variant1, Variant1) => ... // delegate Matching on Variant1 - (Variant2, Variant2, Variant2) => ... // delegate Matching on Variant2 - ... - _ => { - let __this_vi = match this { Variant1 => 0u, Variant2 => 1u, ... }; - let __that_vi = match that { Variant1 => 0u, Variant2 => 1u, ... }; - ... // catch-all remainder can inspect above variant index values. - } - } - ~~~ - */ + /// Creates a match for a tuple of all `self_args`, where either all + /// variants match, or it falls into a catch-all for when one variant + /// does not match. + + /// There are N + 1 cases because is a case for each of the N + /// variants where all of the variants match, and one catch-all for + /// when one does not match. + + /// The catch-all handler is provided access the variant index values + /// for each of the self-args, carried in precomputed variables. (Nota + /// bene: the variant index values are not necessarily the + /// discriminant values. See issue #15523.) + + /// ```{.text} + /// match (this, that, ...) { + /// (Variant1, Variant1, Variant1) => ... // delegate Matching on Variant1 + /// (Variant2, Variant2, Variant2) => ... // delegate Matching on Variant2 + /// ... + /// _ => { + /// let __this_vi = match this { Variant1 => 0u, Variant2 => 1u, ... }; + /// let __that_vi = match that { Variant1 => 0u, Variant2 => 1u, ... }; + /// ... // catch-all remainder can inspect above variant index values. + /// } + /// } + /// ``` fn build_enum_match_tuple( &self, cx: &mut ExtCtxt, @@ -1319,10 +1300,8 @@ impl<'a> TraitDef<'a> { /* helpful premade recipes */ -/** -Fold the fields. `use_foldl` controls whether this is done -left-to-right (`true`) or right-to-left (`false`). -*/ +/// Fold the fields. `use_foldl` controls whether this is done +/// left-to-right (`true`) or right-to-left (`false`). pub fn cs_fold(use_foldl: bool, f: |&mut ExtCtxt, Span, P<Expr>, P<Expr>, &[P<Expr>]| -> P<Expr>, base: P<Expr>, @@ -1361,15 +1340,13 @@ pub fn cs_fold(use_foldl: bool, } -/** -Call the method that is being derived on all the fields, and then -process the collected results. i.e. - -~~~ -f(cx, span, ~[self_1.method(__arg_1_1, __arg_2_1), - self_2.method(__arg_1_2, __arg_2_2)]) -~~~ -*/ +/// Call the method that is being derived on all the fields, and then +/// process the collected results. i.e. +/// +/// ``` +/// f(cx, span, ~[self_1.method(__arg_1_1, __arg_2_1), +/// self_2.method(__arg_1_2, __arg_2_2)]) +/// ``` #[inline] pub fn cs_same_method(f: |&mut ExtCtxt, Span, Vec<P<Expr>>| -> P<Expr>, enum_nonmatch_f: EnumNonMatchCollapsedFunc, @@ -1400,11 +1377,9 @@ pub fn cs_same_method(f: |&mut ExtCtxt, Span, Vec<P<Expr>>| -> P<Expr>, } } -/** -Fold together the results of calling the derived method on all the -fields. `use_foldl` controls whether this is done left-to-right -(`true`) or right-to-left (`false`). -*/ +/// Fold together the results of calling the derived method on all the +/// fields. `use_foldl` controls whether this is done left-to-right +/// (`true`) or right-to-left (`false`). #[inline] pub fn cs_same_method_fold(use_foldl: bool, f: |&mut ExtCtxt, Span, P<Expr>, P<Expr>| -> P<Expr>, @@ -1430,10 +1405,8 @@ pub fn cs_same_method_fold(use_foldl: bool, cx, trait_span, substructure) } -/** -Use a given binop to combine the result of calling the derived method -on all the fields. -*/ +/// Use a given binop to combine the result of calling the derived method +/// on all the fields. #[inline] pub fn cs_binop(binop: ast::BinOp, base: P<Expr>, enum_nonmatch_f: EnumNonMatchCollapsedFunc, |