Generic parameters #258

matthewjasper · 2018-03-03T22:09:13Z

Putting this up to get some feedback. Second PR contains all the major changes.

Add grammar for trait bounds and type parameters (and uses it for trait objects) based on the grammar from @brauliobz's branch, as well as nikomatsakis's parser and jorendorff's grammar.
Gives lifetime parameters some recognition
Documents HRTB (breifly)

Havvy · 2018-03-04T04:54:54Z

src/items/enumerations.md

-[_Generics_]: items.html#type-parameters
-[_WhereClause_]: items.html#type-parameters
+[_Generics_]: items/generics.html
+[_WhereClause_]: iitems/generics.html#where-clauses


iitems -> items

Havvy

I didn't finish this review, but I have to go to work. I really just reviewed items/generics.md before the Where Clauses section.

Overall, this is high quality work, and I'm just found editing things.

Havvy · 2018-03-08T20:22:58Z

src/items/generics.md

+> &nbsp;&nbsp; _LifetimeParam_ (`,` _LifetimeParam_)<sup>\*</sup>  
+>  
+> _LifetimeParam_ :  
+> &nbsp;&nbsp; [LIFETIME_OR_LABEL] [_LifetimeBounds_]<sup>?</sup>  


You want a   or "\ " (I think?) between the links or else markdown is going to think the first link is actually the text for the second link.

Havvy · 2018-03-08T20:23:16Z

src/items/generics.md

+> &nbsp;&nbsp; _TypeParam_ (`,` _TypeParam_)<sup>\*</sup>  
+>  
+> _TypeParam_ :  
+> &nbsp;&nbsp; [IDENTIFIER] [_TypeParamBounds_]<sup>?</sup> ( `=` [_Type_] )<sup>?</sup>  


Likewise here with spaces and links.

Havvy · 2018-03-08T20:25:16Z

src/items/generics.md

+
+Functions, type aliases, structs, enumerations, unions, traits and
+implementations may be *parameterized* by types and lifetimes. These parameters
+are listed in angle brackets (`<...>`), after the name of the item (except for


For the angle brackets parenthesis, you'll want to wrap it and the word before it in a <span class="parenthetical">.

For the second parenthetical, is there a way to write it without using parentheticals at all?

Havvy · 2018-03-08T20:28:35Z

src/items/generics.md

+```
+
+Certain built in types: [references], [raw pointers], [arrays],
+[slices][arrays], [tuples] and [function pointers], have lifetime or type


Nit: built-in*

Nit: trailing comma after "function pointers"

Less nitty: Is the prefix of saying they are built-in types necessary here? The text would flow more smoothly if you just started at "References", IMO.

Havvy · 2018-03-08T20:28:52Z

src/items/generics.md

+
+Certain built in types: [references], [raw pointers], [arrays],
+[slices][arrays], [tuples] and [function pointers], have lifetime or type
+parameters as well, but use different syntax.


Nit: "use a different"

Havvy

Works done. Here's the rest of the review.

I'm basically 😍 looking at this. The content is fantastic.

Havvy · 2018-03-09T07:01:50Z

src/items/generics.md

+> &nbsp;&nbsp; [_Lifetime_](#type-and-lifetime-parameters) [_LifetimeBounds_]  
+>  
+> _TypeBoundWhereClauseItem_ :  
+> &nbsp;&nbsp; _ForLifetimes_<sup>?</sup> [_Type_] `:` [_TypeParamBounds_]  


I feel like ForLifetimes should be defined in this section for now, even if we move it later.

Havvy · 2018-03-09T07:03:16Z

src/items/generics.md

+> _TypeBoundWhereClauseItem_ :  
+> &nbsp;&nbsp; _ForLifetimes_<sup>?</sup> [_Type_] `:` [_TypeParamBounds_]  
+
+Where clauses provide an alternative way to specify bounds on type and lifetime


Nit: Where clauses should be italicized. I've used * for this myself, and others have used _.

Havvy · 2018-03-09T07:03:46Z

src/items/generics.md

+> &nbsp;&nbsp; _ForLifetimes_<sup>?</sup> [_Type_] `:` [_TypeParamBounds_]  
+
+Where clauses provide an alternative way to specify bounds on type and lifetime
+parameters, as well as a way to specify bounds on types that aren't type


Nit: English is weird, but I don't think that comma needs to be there.

Havvy · 2018-03-09T07:20:15Z

src/items/traits.md

-    draw_twice(surface, sh2); // Can call this since U: Shape
-}
-```
+Generic items may use traits as [bounds] on their type parameters.


If you're going to gut this section, then fold this into another section somehow.

Havvy · 2018-03-09T07:23:48Z

src/items/generics.md

+> _TypeBoundWhereClauseItem_ :  
+> &nbsp;&nbsp; _ForLifetimes_<sup>?</sup> [_Type_] `:` [_TypeParamBounds_]  
+
+Where clauses provide an alternative way to specify bounds on type and lifetime


I would get rid of the word "alternative" as it makes it feel like trait bounds in the type parameter lists is the primary way.

Havvy · 2018-03-09T07:37:54Z

src/trait-bounds.md

+
+## Lifetime bounds
+
+Lifetime bounds can be applied to other lifetimes, or to types. The bound


Nit: to types or other lifetimes

Havvy · 2018-03-09T07:38:38Z

src/trait-bounds.md

+
+Lifetime bounds can be applied to other lifetimes, or to types. The bound
+`'a: 'b` is usually read as `'a` *outlives* `'b`. `'a: 'b` means that `'a`
+includes all points in the code that `'b` does.


A bit fuzzy here, but we don't really describe what a point in the code is.

Havvy · 2018-03-09T07:43:42Z

src/trait-bounds.md

+
+> **<sup>Syntax</sup>**  
+> _ForLifetimes_ :  
+> &nbsp;&nbsp; `for` `<` ( [_LifetimeParams_][generic][^unused_for_bounds]


The same issue is happening here with the [^unused_for_bounds] thing. I think the grammar is busy enough without footnotes distracting you away from it.

Havvy · 2018-03-09T07:45:25Z

src/trait-bounds.md

+
+Type bounds may be *higher ranked* over lifetimes. A bound such as `for<'a> &'a
+T: PartialEq<T>` can be used to show `&'a T: PartialEq<T>` for any lifetime.
+For example, only a higher-ranked bound can be used here as the lifetime of the


Nit: The "For example" should be placed on the previous sentence.

Havvy · 2018-03-09T07:47:45Z

src/trait-bounds.md

+> &nbsp;&nbsp; `for` `<` ( [_LifetimeParams_][generic][^unused_for_bounds]
+> `,`<sup>?</sup> ) <sup>?</sup> `>`
+
+Type bounds may be *higher ranked* over lifetimes. A bound such as `for<'a> &'a


Given that the rest of this section is either examples or the scope of the bound, there's not much here explaining abstractly what higher ranked lifetimes are.

matthewjasper · 2018-03-17T14:02:05Z

Comments addressed, I think?

alercah · 2018-05-03T17:06:32Z

src/types.md

@@ -334,7 +334,7 @@ let foo_ptr_2 = if want_i32 {
 };
 ```

-All function items implement [Fn], [FnMut], [FnOnce], [Copy], [Clone], [Send], 
+All function items implement [Fn], [FnMut], [FnOnce], [Copy], [Clone], [Send],


These should be in teletype.

alercah

I have one very minor nit, it looks good to me otherwise but I think I'd like to have @Havvy do another pass since he did the first review.

matthewjasper · 2018-05-05T12:40:34Z

rebased, but CI still can't build mdbook.

Havvy · 2018-05-11T00:27:49Z

Is it possible to rerun CI?

matthewjasper · 2018-05-11T23:26:46Z

Pushed another commit, CI hasn't changed.

Havvy · 2018-05-12T02:08:48Z

The tests are passing on my computer, and TravisCI is acting weird, so merging as is.

Havvy reviewed Mar 4, 2018

View reviewed changes

Havvy requested changes Mar 8, 2018

View reviewed changes

Havvy requested changes Mar 9, 2018

View reviewed changes

matthewjasper force-pushed the generic-parameters branch from 80000d4 to ffd1096 Compare March 17, 2018 14:00

matthewjasper mentioned this pull request Mar 25, 2018

Document impl trait (RFC #1522, RFC #1951, RFC #2250) #276

Open

alercah reviewed May 3, 2018

View reviewed changes

matthewjasper added 2 commits May 5, 2018 13:28

Move type parameters and trait bounds to their own page

418a598

More docs for generic parameters and trait bounds

ff9bfb2

matthewjasper force-pushed the generic-parameters branch from e82338e to 642ae9d Compare May 5, 2018 12:31

Havvy approved these changes May 11, 2018

View reviewed changes

matthewjasper added 2 commits May 12, 2018 00:12

Fix link typo

2e33885

Fix a couple of typos and clarify what bounds are global

00d5651

matthewjasper force-pushed the generic-parameters branch from 642ae9d to 00d5651 Compare May 11, 2018 23:19

Havvy merged commit d9e6a59 into rust-lang:master May 12, 2018

matthewjasper deleted the generic-parameters branch October 18, 2018 21:02

ehuss mentioned this pull request Jan 9, 2021

Add more details about const generics. #921

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Generic parameters #258

Generic parameters #258

matthewjasper commented Mar 3, 2018 •

edited

Loading

Havvy Mar 4, 2018

Havvy left a comment

Havvy Mar 8, 2018

Havvy Mar 8, 2018

Havvy Mar 8, 2018

Havvy Mar 8, 2018

Havvy Mar 8, 2018

Havvy Mar 8, 2018

Havvy left a comment

Havvy Mar 9, 2018

Havvy Mar 9, 2018

Havvy Mar 9, 2018

Havvy Mar 9, 2018

Havvy Mar 9, 2018

Havvy Mar 9, 2018

Havvy Mar 9, 2018

Havvy Mar 9, 2018

Havvy Mar 9, 2018

Havvy Mar 9, 2018

matthewjasper commented Mar 17, 2018

alercah May 3, 2018

alercah left a comment

matthewjasper commented May 5, 2018

Havvy commented May 11, 2018

matthewjasper commented May 11, 2018

Havvy commented May 12, 2018


		## Lifetime bounds

		Lifetime bounds can be applied to other lifetimes, or to types. The bound

Generic parameters #258

Generic parameters #258

Conversation

matthewjasper commented Mar 3, 2018 • edited Loading

Choose a reason for hiding this comment

Havvy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Havvy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matthewjasper commented Mar 17, 2018

Choose a reason for hiding this comment

alercah left a comment

Choose a reason for hiding this comment

matthewjasper commented May 5, 2018

Havvy commented May 11, 2018

matthewjasper commented May 11, 2018

Havvy commented May 12, 2018

matthewjasper commented Mar 3, 2018 •

edited

Loading