Move associated items to their own page. #214

Havvy · 2018-01-23T18:59:06Z

Because they are a cutting concern between impls and traits, they don't really fit in either.

If anybody has concrete suggestions for how to make this better, I'm all ears. I'm not a fan of a lot of my writing in this PR. Especially the definitions.

alercah · 2018-01-23T19:05:59Z

src/items/associated-items.md

+*Associated Items* are the items declared in [traits] or defined in
+[implementations]. They are called this because they are defined on an associate
+type &mdash; the type in the implementation. They are a subset of the kinds of
+items you can declare in a module. Specifically, there are [associated


Perhaps "associated functions (including methods)"?

alercah · 2018-01-23T19:07:28Z

src/items/associated-items.md

+
+*Associated functions* are [functions] associated with a type.
+
+An *associated function declaration* is written as `fn`, then an [identifier]


This applies throughout the doc: spelling grammar out explicitly in words seems verbose and hard to read. Moreover, this seems redundant with regular function grammar. Do we have a BNF standard we can use? Or perhaps update the grammar page and link to that?

alercah · 2018-01-23T19:08:35Z

src/items/associated-items.md

+```
+
+When the associated function is declared on a trait, the function can be called
+on the trait. When this happens, it is substituted for


"on both the trait and on any type implementing the trait"?

alercah · 2018-01-23T19:09:17Z

src/items/associated-items.md

+let x: f64 = f64::from_i32(42);
+```
+
+Associated functions whose first parameter is named `self` are called *methods*


I feel like methods should be their own shorthand, perhaps?

alercah · 2018-01-23T19:09:36Z

src/items/associated-items.md

+and may be invoked using the [method call operator], for example, `x.foo()`, as
+well as the usual function call notation.
+
+When the first parameter is named `self`, the following shorthands may be used:


Are lifetimes permitted in shorthands? e.g. &'a self

alercah · 2018-01-23T19:10:41Z

src/items/associated-items.md

+An *associated type definition* is written as `type`, then an [identifier], then
+an `=`, and finally a [type].
+
+If an item `Item` has an associated type `Assoc`, then `Item::Assoc` is a type


Does Self count as a built-in associated type? I feel like it should be mentioned here.

alercah · 2018-01-23T19:11:33Z

src/items/associated-items.md

+
+An *associated constant definition* is written as a declaraction, but between
+the type and the `;`, there is an `=` followed by a [constant expression].
+


Perhaps add more discussion of how to refer to associated constants, as you did with types? e.g. Item::Const

alercah · 2018-01-23T19:12:18Z

src/items/functions.md

 when called evaluates to a direct call to the function.

-[function item type]: types.html#function-item-types
+[*function item type*]: types.html#function-item-types


Move the formatting outside the link makes more sense to me, perhaps. I wasn't even aware this link syntax worked with formatting.

matthewjasper · 2018-01-23T19:25:23Z

src/items/associated-items.md

@@ -0,0 +1,260 @@
+# Associated Items
+
+*Associated Items* are the items declared in [traits] or defined in


matthewjasper · 2018-01-23T19:58:14Z

src/items/associated-items.md

+```
+
+This defines a trait with two methods. All values that have [implementations]
+of this trait in scope can have their `draw` and `bounding_box` methods called.


Is an implementation being in scope defined anywhere?

You misread; it's the traits that have scope (visibility?), not the implementations. Either way, gonna have to reword this to avoid that confusion.

matthewjasper · 2018-01-23T21:34:52Z

src/items/associated-items.md

+* `self` -> `self: Self`
+* `&self` -> `self: &Self`
+* `&mut self` -> `&mut Self`
+* `Box<self>` -> `self: Box<Self>`


Box<self> isn't valid

matthewjasper · 2018-01-23T22:37:10Z

src/items/associated-items.md

+An *associated type definition* is written as `type`, then an [identifier], then
+an `=`, and finally a [type].
+
+If an item `Item` has an associated type `Assoc`, then `Item::Assoc` is a type


Unfortunately this doesn't work usually (except for type parameters, which are special). The <Type as Trait>::Item syntax needs to be used.

matthewjasper

A few technical things. Might give some comments on the writing later.

Havvy · 2018-02-02T01:47:15Z

Well, took me long enough, but I've addressed feedback where I can.

Havvy · 2018-02-02T01:59:26Z

~~The TravisCI failure is not against the latest change. Seems I might have confused TravisCI with multiple pushes to my branch. >_>~~

That's a different semicolon.

matthewjasper

Thoughts reading through this again. Mostly wording suggestions.

matthewjasper · 2018-02-03T21:40:13Z

src/items/associated-items.md

+
+An *associated function declaration* declares a specification for an associated
+function definition. It is written as a function item, except the
+function block is replaced with a `;`.


function body?

matthewjasper · 2018-02-03T21:40:18Z

src/items/associated-items.md

+
+* `self` -> `self: Self`
+* `&'lifetime self` -> `self: &'lifetime Self`
+* `&'lifetime mut self` -> `&'lifetime mut Self`


missing a self.

matthewjasper · 2018-02-03T21:41:14Z

src/items/associated-items.md

+
+*Associated functions* are [functions] associated with a type.
+
+An *associated function declaration* declares a specification for an associated


'signature' instead of 'specification'

matthewjasper · 2018-02-03T21:46:31Z

src/items/associated-items.md

+function definition. It is written as a function item, except the
+function block is replaced with a `;`.
+
+The identifier if the name of the function. The generics declares types for


This paragraph is referring to removed text.

matthewjasper · 2018-02-03T21:50:21Z

src/items/associated-items.md

+The identifier if the name of the function. The generics declares types for
+usage in the rest of the function declaration. The generics, parameter list,
+return type, and where clause must be the same in the associated function
+definition.


There is some flexibility here from subtyping and weaker/equivalent where clauses, but this is probably OK for now.

matthewjasper · 2018-02-03T22:15:44Z

src/items/associated-items.md

+
+An *associated type declaration* declares a specification for associated type
+definitions. It is written as `type`, then an [identifier], and
+finally an optional trait bounds.


"list of trait bounds"

matthewjasper · 2018-02-03T22:17:02Z

src/items/associated-items.md

+An *associated type definition* defines a type alias on another type. It is 
+written as `type`, then an [identifier], then an `=`, and finally a [type].
+
+If an item `Item` has an associated type `Assoc` from a trait `Trait`, then 


matthewjasper · 2018-02-03T22:17:59Z

src/items/associated-items.md

+If an item `Item` has an associated type `Assoc` from a trait `Trait`, then 
+`<Item as Trait>::Assoc` is a type that is an alias of the type specified in the
+associated type definition. Furthermore, `Item::Assoc` can be used in type
+parameters.


If Item is a type parameter.

matthewjasper · 2018-02-03T23:06:43Z

src/items/associated-items.md

+
+*Associated constants* are [constants] associated with a type.
+
+An *associated constant declaration* declares a specificatoin for associated


specificatoin -> specification

matthewjasper · 2018-02-03T23:08:32Z

src/items/associated-items.md

+The identifier is the name of the constant used in the path. The type is the
+type that the definition has to implement.
+
+An *associated constant definition* defines a constant associated with another


Havvy · 2018-02-12T02:04:29Z

Updated.

matthewjasper · 2018-02-12T22:08:51Z

Thanks!

alercah reviewed Jan 23, 2018

View reviewed changes

matthewjasper reviewed Jan 24, 2018

View reviewed changes

ghost mentioned this pull request Jan 29, 2018

link to associated constants bitflags/bitflags#148

Closed

Move associated items to their own page.

79c14b6

Havvy force-pushed the assoc-items branch 2 times, most recently from bb3dec8 to a8a40b8 Compare February 2, 2018 01:42

Address assoc-item feedback.

2a31152

Havvy force-pushed the assoc-items branch from a8a40b8 to 2a31152 Compare February 2, 2018 02:01

matthewjasper requested changes Feb 3, 2018

View reviewed changes

Address associated items feedback round 2

bf9ba61

matthewjasper approved these changes Feb 12, 2018

View reviewed changes

matthewjasper merged commit e2e3652 into rust-lang:master Feb 12, 2018

matthewjasper mentioned this pull request Feb 12, 2018

Hide more lines in code example #242

Merged

Havvy deleted the assoc-items branch February 19, 2018 08:35


		Associated functions are [functions] associated with a type.

		An associated function declaration is written as `fn`, then an [identifier]


		An associated constant definition is written as a declaraction, but between
		the type and the `;`, there is an `=` followed by a [constant expression].

		@@ -0,0 +1,260 @@
		# Associated Items

		Associated Items are the items declared in [traits] or defined in


		Associated functions are [functions] associated with a type.

		An associated function declaration declares a specification for an associated


		Associated constants are [constants] associated with a type.

		An associated constant declaration declares a specificatoin for associated

Move associated items to their own page. #214

Move associated items to their own page. #214

Uh oh!

Conversation

Havvy commented Jan 23, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewjasper left a comment

Choose a reason for hiding this comment

Uh oh!

Havvy commented Feb 2, 2018

Uh oh!

Havvy commented Feb 2, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

matthewjasper left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Havvy commented Feb 12, 2018

Uh oh!

matthewjasper commented Feb 12, 2018

Uh oh!

Uh oh!

Havvy commented Feb 2, 2018 •

edited

Loading