Merge pull request #275 from alercah/methods

More cleanups related to methods.

Author: matthewjasper

src/expressions/method-call-expr.md

@@ -2,10 +2,10 @@
 
 A _method call_ consists of an expression (the *receiver*) followed by a single
 dot, an [identifier], and a parenthesized expression-list. Method calls are
-resolved to associated methods of specific types, either statically dispatching
-to a method if the exact `self`-type of the left-hand-side is known, or
-dynamically dispatching if the left-hand-side expression is an indirect [trait
-object](types.html#trait-objects).
+resolved to associated [methods] on specific traits, either statically
+dispatching to a method if the exact `self`-type of the left-hand-side is known,
+or dynamically dispatching if the left-hand-side expression is an indirect
+[trait object](types.html#trait-objects).
 
 ```rust
 let pi: Result<f32, _> = "3.14".parse();
@@ -95,3 +95,4 @@ and function invocation.
 [trait objects]: types.html#trait-objects
 [disambiguate call]: expressions/call-expr.html#disambiguating-function-calls
 [dereference]: expressions/operator-expr.html#the-dereference-operator
+[methods]: items/associated-items.html#methods

src/items/associated-items.md

@@ -77,15 +77,19 @@ let _: f64 = <f64 as Num>::from_i32(42);
 let _: f64 = f64::from_i32(42);
 ```
 
+### Methods
+
 Associated functions whose first parameter is named `self` are called *methods*
 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.
+The `self` parameter must have one of the following types. As a result, the
+following shorthands may be used to declare `self`:
 
 * `self` -> `self: Self`
 * `&'lifetime self` -> `self: &'lifetime Self`
 * `&'lifetime mut self` -> `self: &'lifetime mut Self`
+* `self : Box<Self>` (no shorthand)
 
 > Note: Lifetimes can be and usually are elided with this shorthand.
 

src/items/functions.md

@@ -7,16 +7,10 @@ as parameters, through which the caller passes arguments into the function, and
 the *output* [*type*][type] of the value the function will return to its caller
 on completion.
 
-[block]: expressions/block-expr.html
-[variables]: variables.html
-[type]: types.html
-
 When referred to, a _function_ yields a first-class *value* of the
 corresponding zero-sized [*function item type*], which
 when called evaluates to a direct call to the function.
 
-[*function item type*]: types.html#function-item-types
-
 For example, this is a simple function:
 ```rust
 fn answer_to_life_the_universe_and_everything() -> i32 {
@@ -61,7 +55,7 @@ fn foo<A, B>(x: A, y: B) {
 ```
 
 Inside the function signature and body, the name of the type parameter can be
-used as a type name. [Trait](items/traits.html) bounds can be specified for type
+used as a type name. [Trait] bounds can be specified for type
 parameters to allow methods with that trait to be called on values of that
 type. This is specified using the `where` syntax:
 
@@ -91,8 +85,6 @@ component after the function name. This might be necessary if there is not
 sufficient context to determine the type parameters. For example,
 `mem::size_of::<u32>() == 4`.
 
-[path]: paths.html
-
 ## Extern functions
 
 Extern functions are part of Rust's foreign function interface, providing the
@@ -124,3 +116,9 @@ of an extern function will cause the process to abort. In LLVM, this is
 implemented by executing an illegal instruction.
 
 [external blocks]: items/external-blocks.html
+[path]: paths.html
+[block]: expressions/block-expr.html
+[variables]: variables.html
+[type]: types.html
+[*function item type*]: types.html#function-item-types
+[Trait]: items/traits.html

src/items/traits.md

@@ -14,14 +14,19 @@ other traits and so forth as usual.
 
 Traits are implemented for specific types through separate [implementations].
 
+Items associated with a trait do not need to be defined in the trait, but they
+may be. If the trait provides a definition, then this definition acts as a
+default for any implementation which does not override it. If it does not, then
+any implementation must provide a definition.
+
 ## Trait bounds
 
 Generic functions may use traits as _bounds_ on their type parameters. This
 will have three effects:
 
 - Only types that have the trait may instantiate the parameter.
-- Within the generic function, the methods of the trait can be called on values
-  that have the parameter's type. Associated types can be used in the
+- Within the generic function, the functions of the trait can be called on
+  values that have the parameter's type. Associated types can be used in the
   function's signature, and associated constants can be used in expressions
   within the function body.
 - Generic functions and types with the same or weaker bounds can use the
@@ -63,11 +68,10 @@ Object safe traits can be the base trait of a [trait object]. A trait is
 *object safe* if it has the following qualities (defined in [RFC 255]):
 
 * It must not require `Self: Sized`
-* All associated functions must either have a `where Self: Sized` bound or
-    * Not have any type parameters (although lifetime parameters are allowed)
-    * Must be a method: its first parameter must be called self, with type
-      `Self`, `&Self`, `&mut Self`, `Box<Self>`.
-    * `Self` may only be used in the type of the receiver.
+* All associated functions must either have a `where Self: Sized` bound, or
+    * Not have any type parameters (although lifetime parameters are allowed),
+      and
+    * Be a [method] that does not use `Self` except in the type of the receiver.
 * It must not have any associated constants.
 
 ## Supertraits
@@ -142,6 +146,6 @@ let nonsense = mycircle.radius() * mycircle.area();
 [`RefUnwindSafe`]: ../std/panic/trait.RefUnwindSafe.html
 [trait object]: types.html#trait-objects
 [explicit]: expressions/operator-expr.html#type-cast-expressions
-[methods called]: expressions/method-call-expr.html
 [RFC 255]: https://github.com/rust-lang/rfcs/blob/master/text/0255-object-safety.md
-[associated items]: items/associated-items.html
+[associated items]: items/associated-items.html
+[method]: items/functions.html#methods