Merge pull request scala#4404 from soc/topic/spec

Spec improvements

Author: adriaanm

spec/01-lexical-syntax.md

@@ -1,5 +1,5 @@
 ---
-title: Identifiers, Names and Scopes
+title: Identifiers, Names & Scopes
 layout: default
 chapter: 2
 ---
@@ -69,7 +69,7 @@ the member of the type $T$ of $e$ which has the name $x$ in the same
 namespace as the identifier. It is an error if $T$ is not a [value type](03-types.html#value-types).
 The type of $e.x$ is the member type of the referenced entity in $T$.
 
-### Example
+###### Example
 
 Assume the following two definitions of objects named `X` in packages `P` and `Q`.
 

spec/02-identifiers-names-and-scopes.md

@@ -147,7 +147,7 @@ A qualified type designator has the form `p.t` where `p` is
 a [path](#paths) and _t_ is a type name. Such a type designator is
 equivalent to the type projection `p.type#t`.
 
-### Example
+###### Example
 
 Some type designators and their expansions are listed below. We assume
 a local type parameter $t$, a value `maintable`
@@ -178,7 +178,8 @@ well-formed if each actual type parameter
 _conforms to its bounds_, i.e. $\sigma L_i <: T_i <: \sigma U_i$ where $\sigma$ is the
 substitution $[ a_1 := T_1 , \ldots , a_n := T_n ]$.
 
-### Example Parameterized Types
+###### Example Parameterized Types
+
 Given the partial type definitions:
 
 ```scala
@@ -202,7 +203,7 @@ F[List, Int]
 G[S, String]
 ```
 
-### Example
+###### Example
 
 Given the [above type definitions](#example-parameterized-types),
 the following types are ill-formed:
@@ -255,10 +256,10 @@ AnnotType  ::=  SimpleType {Annotation}
 ```
 
 An annotated type $T$ $a_1, \ldots, a_n$
-attaches [annotations](11-user-defined-annotations.html#user-defined-annotations)
+attaches [annotations](11-annotations.html#user-defined-annotations)
 $a_1 , \ldots , a_n$ to the type $T$.
 
-### Example
+###### Example
 
 The following type adds the `@suspendable` annotation to the type `String`:
 
@@ -304,7 +305,7 @@ A compound type may also consist of just a refinement
 $\\{ R \\}$ with no preceding component types. Such a type is
 equivalent to `AnyRef` $\\{ R \\}$.
 
-### Example
+###### Example
 
 The following example shows how to declare and use a method which
 a parameter type that contains a refinement with structural declarations.
@@ -500,7 +501,7 @@ or [tuple types](#tuple-types).
 Their expansion is then the expansion in the equivalent parameterized
 type.
 
-### Example
+###### Example
 
 Assume the class definitions
 
@@ -524,15 +525,15 @@ An alternative formulation of the first type above using wildcard syntax is:
 Ref[_ <: java.lang.Number]
 ```
 
-### Example
+###### Example
 
 The type `List[List[_]]` is equivalent to the existential type
 
 ```scala
 List[List[t] forSome { type t }] .
 ```
 
-### Example
+###### Example
 
 Assume a covariant type
 
@@ -658,7 +659,7 @@ same name, we model
 
 An overloaded type consisting of type alternatives $T_1 \commadots T_n (n \geq 2)$ is denoted internally $T_1 \overload \ldots \overload T_n$.
 
-### Example
+###### Example
 ```
 def println: Unit
 def println(s: String): Unit = $\ldots$
@@ -676,7 +677,7 @@ println:  => Unit $\overload$
           [A] (A) (A => String) Unit
 ```
 
-### Example
+###### Example
 ```
 def f(x: T): T = $\ldots$
 val f = 0

spec/03-types.md

@@ -1,5 +1,5 @@
 ---
-title: Basic Declarations and Definitions
+title: Basic Declarations & Definitions
 layout: default
 chapter: 4
 ---
@@ -563,7 +563,7 @@ abstract class Sequence[+A] {
 }
 ```
 
-### Example
+###### Example
 
 ```scala
 abstract class OutputChannel[-A] {

spec/04-basic-declarations-and-definitions.md

@@ -1,5 +1,5 @@
 ---
-title: Classes and Objects
+title: Classes & Objects
 layout: default
 chapter: 5
 ---
@@ -368,7 +368,7 @@ it is possible to add new defaults (if the corresponding parameter in the
 superclass does not have a default) or to override the defaults of the
 superclass (otherwise).
 
-### Example
+###### Example
 
 Consider the definitions:
 
@@ -699,7 +699,7 @@ Here,
     parameter section is called _polymorphic_, otherwise it is called
     _monomorphic_.
   - $as$ is a possibly empty sequence of
-    [annotations](11-user-defined-annotations.html#user-defined-annotations).
+    [annotations](11-annotations.html#user-defined-annotations).
     If any annotations are given, they apply to the primary constructor of the
     class.
   - $m$ is an [access modifier](#modifiers) such as
@@ -744,7 +744,7 @@ which when applied to parameters conforming to types $\mathit{ps}$
 initializes instances of type `$c$[$\mathit{tps}\,$]` by evaluating the template
 $t$.
 
-### Example
+###### Example
 The following example illustrates `val` and `var` parameters of a class `C`:
 
 ```scala
@@ -990,7 +990,7 @@ it is not statically known at the time the trait is defined.
 If $D$ is not a trait, then its actual supertype is simply its
 least proper supertype (which is statically known).
 
-### Example
+###### Example
 The following trait defines the property
 of being comparable to objects of some type. It contains an abstract
 method `<` and default implementations of the other

spec/05-classes-and-objects.md

@@ -205,7 +205,7 @@ to the type or method of $x$ in the parent trait of $C$ whose simple
 name is $T$. That member must be uniquely defined. If it is a method,
 it must be concrete.
 
-### Example
+###### Example
 Consider the following class definitions
 
 ```scala
@@ -778,7 +778,7 @@ Expr1              ::=  PostfixExpr `:' Annotation {Annotation}
 ```
 
 An annotated expression `$e$: @$a_1$ $\ldots$ @$a_n$`
-attaches [annotations](11-user-defined-annotations.html#user-defined-annotations) $a_1 , \ldots , a_n$ to the
+attaches [annotations](11-annotations.html#user-defined-annotations) $a_1 , \ldots , a_n$ to the
 expression $e$.
 
 ## Assignments
@@ -815,7 +815,7 @@ Here are some assignment expressions and their equivalent expansions.
 |`x.f(i) = e`              | `x.f.update(i, e)`   |
 |`x.f(i, j) = e`           | `x.f.update(i, j, e)`|
 
-### Example Imperative Matrix Multiplication
+###### Example Imperative Matrix Multiplication
 
 Here is the usual imperative code for matrix multiplication.
 
@@ -1221,9 +1221,9 @@ In that case, a fresh name for the parameter is chosen arbitrarily.
 
 A named parameter of an anonymous function may be optionally preceded
 by an `implicit` modifier. In that case the parameter is
-labeled [`implicit`](07-implicit-parameters-and-views.html#implicit-parameters-and-views); however the
+labeled [`implicit`](07-implicits.html#implicit-parameters-and-views); however the
 parameter section itself does not count as an implicit parameter
-section in the sense defined [here](07-implicit-parameters-and-views.html#implicit-parameters). Hence, arguments to
+section in the sense defined [here](07-implicits.html#implicit-parameters). Hence, arguments to
 anonymous functions always have to be given explicitly.
 
 ###### Example
@@ -1341,7 +1341,7 @@ available implicit conversions are given in the next two sub-sections.
 
 We say, a type $T$ is _compatible_ to a type $U$ if $T$ weakly conforms
 to $U$ after applying [eta-expansion](#eta-expansion) and
-[view applications](07-implicit-parameters-and-views.html#views).
+[view applications](07-implicits.html#views).
 
 ### Value Conversions
 
@@ -1389,7 +1389,7 @@ term `{ $e$; () }`.
 ###### View Application
 If none of the previous conversions applies, and $e$'s type
 does not conform to the expected type $\mathit{pt}$, it is attempted to convert
-$e$ to the expected type with a [view](07-implicit-parameters-and-views.html#views).
+$e$ to the expected type with a [view](07-implicits.html#views).
 
 ###### Dynamic Member Selection
 If none of the previous conversions applies, and $e$ is a prefix
@@ -1408,7 +1408,7 @@ type $T$ by evaluating the expression to which $m$ is bound.
 
 ###### Implicit Application
 If the method takes only implicit parameters, implicit
-arguments are passed following the rules [here](07-implicit-parameters-and-views.html#implicit-parameters).
+arguments are passed following the rules [here](07-implicits.html#implicit-parameters).
 
 ###### Eta Expansion
 Otherwise, if the method is not a constructor,

spec/06-expressions.md

@@ -1,10 +1,10 @@
 ---
-title: Implicit Parameters and Views
+title: Implicits
 layout: default
 chapter: 7
 ---
 
-# Implicit Parameters and Views
+# Implicits
 
 ## The Implicit Modifier
 
@@ -19,7 +19,8 @@ and can be used as implicit conversions called [views](#views).
 The `implicit` modifier is illegal for all
 type members, as well as for [top-level objects](09-top-level-definitions.html#packagings).
 
-### Example Monoid
+###### Example Monoid
+
 The following code defines an abstract class of monoids and
 two concrete implementations, `StringMonoid` and
 `IntMonoid`. The two implementations are marked implicit.
@@ -180,7 +181,7 @@ To prevent such infinite expansions, the compiler keeps track of
 a stack of “open implicit types” for which implicit arguments are currently being
 searched. Whenever an implicit argument for type $T$ is searched, the
 “core type” of $T$ is added to the stack. Here, the _core type_
-of $T$ is $T$ with aliases expanded, top-level type [annotations](11-user-defined-annotations.html#user-defined-annotations) and
+of $T$ is $T$ with aliases expanded, top-level type [annotations](11-annotations.html#user-defined-annotations) and
 [refinements](03-types.html#compound-types) removed, and occurrences
 of top-level existentially bound variables replaced by their upper
 bounds. The core type is removed from the stack once the search for
@@ -284,7 +285,8 @@ As for implicit parameters, overloading resolution is applied
 if there are several possible candidates (of either the call-by-value
 or the call-by-name category).
 
-### Example Ordered
+###### Example Ordered
+
 Class `scala.Ordered[A]` contains a method
 
 ```scala

spec/07-implicit-parameters-and-views.md renamed to spec/07-implicits.md

@@ -371,7 +371,7 @@ bound type variables in a typed pattern or constructor
 pattern. Inference takes into account the expected type of the
 pattern.
 
-### Type parameter inference for typed patterns.
+### Type parameter inference for typed patterns
 
 Assume a typed pattern $p: T'$. Let $T$ result from $T'$ where all wildcards in
 $T'$ are renamed to fresh variable names. Let $a_1 , \ldots , a_n$ be
@@ -437,7 +437,7 @@ complexity of inferred bounds. Minimality and maximality of types have
 to be understood relative to the set of types of acceptable
 complexity.
 
-#### Type parameter inference for constructor patterns.
+### Type parameter inference for constructor patterns
 Assume a constructor pattern $C(p_1 , \ldots , p_n)$ where class $C$
 has type type parameters $a_1 , \ldots , a_n$.  These type parameters
 are inferred in the same way as for the typed pattern
@@ -593,7 +593,7 @@ the compilation of pattern matching can emit warnings which diagnose
 that a given set of patterns is not exhaustive, i.e. that there is a
 possibility of a `MatchError` being raised at run-time.
 
-### Example
+###### Example
 
 Consider the following definitions of arithmetic terms:
 

spec/08-pattern-matching.md

@@ -1,5 +1,5 @@
 ---
-title: XML Expressions and Patterns
+title: XML
 layout: default
 chapter: 10
 ---

spec/10-xml-expressions-and-patterns.md

@@ -1,17 +1,19 @@
 ---
-title: User-Defined Annotations
+title: Annotations
 layout: default
 chapter: 11
 ---
 
-# User-Defined Annotations
+# Annotations
 
 ```ebnf
   Annotation       ::=  ‘@’ SimpleType {ArgumentExprs}
   ConstrAnnotation ::=  ‘@’ SimpleType ArgumentExprs
 ```
 
-User-defined annotations associate meta-information with definitions.
+## Definition
+
+Annotations associate meta-information with definitions.
 A simple annotation has the form `@$c$` or `@$c(a_1 , \ldots , a_n)$`.
 Here, $c$ is a constructor of a class $C$, which must conform
 to the class `scala.Annotation`.
@@ -33,6 +35,10 @@ String @local                               // Type annotation
 (e: @unchecked) match { ... }               // Expression annotation
 ```
 
+## Predefined Annotations
+
+### Java Platform Annotations
+
 The meaning of annotation clauses is implementation-dependent. On the
 Java platform, the following annotations have a standard meaning.
 
@@ -61,7 +67,7 @@ Java platform, the following annotations have a standard meaning.
     clause for the method or constructor must mention the class of that exception
     or one of the superclasses of the class of that exception.
 
-## Java Beans Annotations
+### Java Beans Annotations
 
   * `@scala.beans.BeanProperty` When prefixed to a definition of some variable `X`, this
     annotation causes getter and setter methods `getX`, `setX`
@@ -76,18 +82,21 @@ Java platform, the following annotations have a standard meaning.
   * `@scala.beans.BooleanBeanProperty` This annotation is equivalent to `scala.reflect.BeanProperty`, but
     the generated getter method is named `isX` instead of `getX`.
 
-## Deprecation Annotations
+### Deprecation Annotations
 
-  * `@deprecated(<stringlit>)` Marks a definition as deprecated. Accesses to the
+  * `@deprecated(message: <stringlit>, since: <stringlit>)`<br/>
+    Marks a definition as deprecated. Accesses to the
     defined entity will then cause a deprecated warning mentioning the
-    message `<stringlit>` to be issued from the compiler.  Deprecated
-    warnings are suppressed in code that belongs itself to a definition
+    _message_ `<stringlit>` to be issued from the compiler.
+    The argument _since_ documents since when the definition should be considered deprecated.<br/>
+    Deprecated warnings are suppressed in code that belongs itself to a definition
     that is labeled deprecated.
 
-  * `@deprecatedName(name: <symbollit>)` Marks a formal parameter name as deprecated. Invocations of this entity
+  * `@deprecatedName(name: <symbollit>)`<br/>
+    Marks a formal parameter name as deprecated. Invocations of this entity
     using named parameter syntax refering to the deprecated parameter name cause a deprecation warning.
 
-## Scala Compiler Annotations
+### Scala Compiler Annotations
 
   * `@unchecked` When applied to the selector of a `match` expression,
     this attribute suppresses any warnings about non-exhaustive pattern
@@ -141,6 +150,8 @@ Java platform, the following annotations have a standard meaning.
     a definition, the compiler will instead use the specialized version.
     See the [specialization sid](http://docs.scala-lang.org/sips/completed/scala-specialization.html) for more details of the implementation.
 
+## User-defined Annotations
+
 Other annotations may be interpreted by platform- or
 application-dependent tools. Class `scala.Annotation` has two
 sub-traits which are used to indicate how these annotations are