From 9b49ad238db64f66d66a1a6e9c26198abe56cc53 Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Tue, 16 Sep 2014 13:27:34 +0200 Subject: doc: Cleanup. Remove ~~~ for code block specification. Use /// Over /** */ for doc blocks. --- src/libsyntax/ext/deriving/generic/mod.rs | 272 ++++++++++++++---------------- 1 file changed, 123 insertions(+), 149 deletions(-) (limited to 'src/libsyntax/ext') diff --git a/src/libsyntax/ext/deriving/generic/mod.rs b/src/libsyntax/ext/deriving/generic/mod.rs index ff249495bd7..31b242da27b 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: //! name: Some(), //! self_: , //! other: ~[, //! name: None, //! //! ~[] //! }]) -//! ~~~ +//! ``` //! //! ## Enums //! //! When generating the `expr` for a call with `self == C0(a)` and `other //! == C0(b)`, the SubstructureFields is //! -//! ~~~text +//! ```{.text} //! EnumMatching(0, , //! ~[FieldInfo { //! span: @@ -134,11 +134,11 @@ //! self_: , //! other: ~[] //! }]) -//! ~~~ +//! ``` //! //! For `C1 {x}` and `C1 {x}`, //! -//! ~~~text +//! ```{.text} //! EnumMatching(1, , //! ~[FieldInfo { //! span: @@ -146,16 +146,16 @@ //! self_: , //! other: ~[] //! }]) -//! ~~~ +//! ``` //! //! For `C0(a)` and `C1 {x}` , //! -//! ~~~text +//! ```{.text} //! EnumNonMatchingCollapsed( //! ~[, ], //! &[, ], //! &[, ]) -//! ~~~ +//! ``` //! //! 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(, Named(~[(, )])) //! //! StaticStruct(, Unnamed(~[])) @@ -178,7 +178,7 @@ //! StaticEnum(, ~[(, , Unnamed(~[])), //! (, , //! Named(~[(, )]))]) -//! ~~~ +//! ``` use std::cell::RefCell; use std::gc::GC; @@ -286,21 +286,17 @@ pub enum StaticFields { /// and examples pub enum SubstructureFields<'a> { Struct(Vec), - /** - 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), - /** - 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 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. EnumNonMatchingCollapsed(Vec, &'a [P], &'a [Ident]), /// A static method where Self is a struct. @@ -311,20 +307,16 @@ pub enum SubstructureFields<'a> { -/** -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, see above for details. pub type CombineSubstructureFunc<'a> = |&mut ExtCtxt, Span, &Substructure|: 'a -> P; -/** -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, @@ -374,18 +366,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 { ... } - * ``` - * - * 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 { ... } + /// ``` + /// + /// where B1, B2, ... are the bounds given by `bounds_paths`.' fn create_derived_impl(&self, cx: &mut ExtCtxt, type_ident: Ident, @@ -694,27 +682,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, @@ -799,37 +785,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, @@ -843,33 +827,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, @@ -1320,10 +1302,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, P, &[P]| -> P, base: P, @@ -1362,15 +1342,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, enum_nonmatch_f: EnumNonMatchCollapsedFunc, @@ -1401,11 +1379,9 @@ pub fn cs_same_method(f: |&mut ExtCtxt, Span, Vec>| -> P, } } -/** -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, P| -> P, @@ -1431,10 +1407,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, enum_nonmatch_f: EnumNonMatchCollapsedFunc, -- cgit 1.4.1-3-g733a5 From f38f0b2e1af79766d13a18b506158ac32b16ce04 Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Wed, 17 Sep 2014 15:02:26 +0200 Subject: doc: Backticks and spelling mistakes. --- src/libcore/option.rs | 2 +- src/libsyntax/ext/deriving/generic/mod.rs | 26 +++++++++++++------------- 2 files changed, 14 insertions(+), 14 deletions(-) (limited to 'src/libsyntax/ext') diff --git a/src/libcore/option.rs b/src/libcore/option.rs index 6020f7ce7f5..c98a2d12485 100644 --- a/src/libcore/option.rs +++ b/src/libcore/option.rs @@ -327,7 +327,7 @@ impl Option { /// Instead, prefer to use pattern matching and handle the `None` /// case explicitly. /// - /// # Examle + /// # Example /// /// ``` /// let x = Some("air"); diff --git a/src/libsyntax/ext/deriving/generic/mod.rs b/src/libsyntax/ext/deriving/generic/mod.rs index 31b242da27b..514035f04e0 100644 --- a/src/libsyntax/ext/deriving/generic/mod.rs +++ b/src/libsyntax/ext/deriving/generic/mod.rs @@ -253,7 +253,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], /// verbatim access to any other arguments pub nonself_args: &'a [P], @@ -270,7 +270,7 @@ pub struct FieldInfo { /// (specifically, a reference to it). pub self_: P, /// The expressions corresponding to references to this field in - /// the other Self arguments. + /// the other `Self` arguments. pub other: Vec>, } @@ -291,17 +291,17 @@ pub enum SubstructureFields<'a> { /// variant. EnumMatching(uint, &'a ast::Variant, Vec), - /// 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 + /// 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 - /// Idents bound to the variant index values for each of the actual - /// input Self arguments. + /// `Ident`s bound to the variant index values for each of the actual + /// input `Self` arguments. EnumNonMatchingCollapsed(Vec, &'a [P], &'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)>), } @@ -313,10 +313,10 @@ pub type CombineSubstructureFunc<'a> = |&mut ExtCtxt, Span, &Substructure|: 'a -> P; /// Deal with non-matching enum variants. The tuple is a list of -/// identifiers (one for each Self argument, which could be any of the +/// 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. +/// 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, @@ -370,7 +370,7 @@ impl<'a> TraitDef<'a> { /// 'z, A, ..., Z>`, creates an impl like: /// /// ```ignore - /// impl<'a, ..., 'z, A:Tr B1 B2, ..., Z: Tr B1 B2> Tr for T { ... } + /// impl<'a, ..., 'z, A:Tr B1 B2, ..., Z: Tr B1 B2> Tr for T { ... } /// ``` /// /// where B1, B2, ... are the bounds given by `bounds_paths`.' -- cgit 1.4.1-3-g733a5 From a0d502b0ed096397b7cccde37ec7139011ce7e9a Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Wed, 17 Sep 2014 15:12:58 +0200 Subject: doc: Remove "see above". --- src/libsyntax/ext/deriving/generic/mod.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'src/libsyntax/ext') diff --git a/src/libsyntax/ext/deriving/generic/mod.rs b/src/libsyntax/ext/deriving/generic/mod.rs index 514035f04e0..10fd515dee9 100644 --- a/src/libsyntax/ext/deriving/generic/mod.rs +++ b/src/libsyntax/ext/deriving/generic/mod.rs @@ -276,14 +276,13 @@ pub struct FieldInfo { /// Fields for a static method pub enum StaticFields { - /// Tuple structs/enum variants like this + /// Tuple structs/enum variants like this. Unnamed(Vec), /// 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), /// Matching variants of the enum: variant index, ast::Variant, @@ -308,7 +307,7 @@ pub enum SubstructureFields<'a> { /// Combine the values of all the fields together. The last argument is -/// all the fields of all the structures, see above for details. +/// all the fields of all the structures. pub type CombineSubstructureFunc<'a> = |&mut ExtCtxt, Span, &Substructure|: 'a -> P; -- cgit 1.4.1-3-g733a5