Add basic GATs reference information

[jackh726]

There really isn't a ton to add here. Almost all of the syntax related to GATs falls out from existing syntax.

[dhardy]

Also in src/items/associated-items.md:207:

This paragraph gives a wordy description of syntax for associated type declarations. This isn't very easy to follow and isn't updated regarding GATs. I suggest something like the following:

An associated type declaration declares a signature for associated type definitions. It is written in one of the following forms, where Assoc is the name of the associated type, Params is a comma-separated list of type, lifetime or const parameters, Bounds is a plus-separated list of trait bounds on the associated type, and WhereBounds is a comma-separated list of bounds on parameters:

type Assoc;
type Assoc: Bounds;
type Assoc<Params>;
type Assoc<Params>: Bounds;
type Assoc<Params> where WhereBounds;
type Assoc<Params>: Bounds where WhereBounds;

Similarly for assoc. type definitions, para from line 215.

[BurntSushi]

Does anything about where clauses like, e.g., Self: 'a, need to be added here? I'm thinking about this specifically: https://rust-lang.github.io/generic-associated-types-initiative/explainer/required_bounds.html

[ehuss]

Thanks for posting this!

Unfortunately I don't know enough to even get started on what to cover. I see things like the Object safety list needs to be updated?

[jackh726]

Does anything about where clauses like, e.g., Self: 'a, need to be added here? I'm thinking about this specifically: https://rust-lang.github.io/generic-associated-types-initiative/explainer/required_bounds.html

I can try to add a short explanation

[nikomatsakis]

This looks good. I have a few minor suggestions, @jackh726.

[nikomatsakis]

It occurs to me that it would be worth clarifying the distinction between Bounds and WhereBounds!

[jackh726]

That is stated in the paragraph above? Should we be more detailed?

[nikomatsakis]

I think we could be more explicit. Left some suggestions. WDYT?

[ehuss]

This clause by itself doesn't seem to be correct to me. It seems to imply that the following is not allowed:

type X = i32;

Perhaps this could be turned around so that it specifically says what a trait impl associated type needs? A sentence could be added to the previous paragraph, since they are talking about the same thing. Maybe something like this:

A type alias without the [Type] specification may only appear as an [associated type] in a [trait].
Associated types in a [trait impl] must include the [Type] specification.

[jackh726]

I've made a separate paragraph for each for of type aliases, to be specific about what is allow, what is required, and what isn't allowed in each.

[nikomatsakis]

Suggested change

	lifetime or const parameters, `Bounds` is a plus-separated list of trait bounds
	on the associated type, and `WhereBounds` is a comma-separated list of bounds on
	parameters:
	lifetime or const parameters, `Bounds` is a plus-separated list of trait bounds
	that the associated type must meet, and `WhereBounds` is a comma-separated list of bounds that the parameters must meet:

[nikomatsakis]

Maybe something like

Relationship between Bounds and WhereBounds

In this example:

trait Example {
    type Output<T>: Ord where T: Debug
}

Given a reference to the associated type like <X as Example>::Output<Y>, the associated type itself must be Ord, and the type Y must be Debug.

[nikomatsakis]

I think we could be more explicit. Left some suggestions. WDYT?