From 990b3c7682d9b0655518e20274673aade75dbed0 Mon Sep 17 00:00:00 2001 From: Simon Ochsenreither Date: Mon, 17 Sep 2012 13:45:43 +0200 Subject: SI-6380 #1 Add @throws[Exception] This change allows an additional notation of the @throws annotation: Old-style: @throws(classOf[Exception]) New-style: @throws[Exception] The optional String argument moves @throws in line with @deprecated, @migration, etc. and prevents confusion caused by the default inheritance of ScalaDoc comments and the non-inheritance of annotations. Before: /** This method does ... * @throws IllegalArgumentException if `a` is less than 0. */ @throws(classOf[IllegalArgumentException]) def foo(a: Int) = ... Now: /** This method does ... */ @throws[IllegalArgumentException]("if `a` is less than 0") def foo(a: Int) = ... ScalaDoc @throws tags remain supported for cases where documentation of thrown exceptions is needed, but are not supposed to be added to the exception attribute of the class file. In this commit the necessary compiler support is added. The code to extract exceptions from annotations is now shared instead of being duplicated all over the place. The change is completely source and binary compatible, except that the code is now enforcing that the type thrown is a subtype of Throwable as mandated by the JVM spec instead of allowing something like @throws(classOf[String]). Not in this commit: - ScalaDoc support to add the String argument to ScalaDoc's exception list - Adaption of the library --- src/library/scala/throws.scala | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'src/library') diff --git a/src/library/scala/throws.scala b/src/library/scala/throws.scala index 0aa0d31c9f..02dffb00b0 100644 --- a/src/library/scala/throws.scala +++ b/src/library/scala/throws.scala @@ -14,7 +14,7 @@ package scala * {{{ * class Reader(fname: String) { * private val in = new BufferedReader(new FileReader(fname)) - * @throws(classOf[IOException]) + * @throws[IOException]("if the file doesn't exist") * def read() = in.read() * } * }}} @@ -23,4 +23,6 @@ package scala * @version 1.0, 19/05/2006 * @since 2.1 */ -class throws(clazz: Class[_]) extends scala.annotation.StaticAnnotation +class throws[T <: Throwable](cause: String = "") extends scala.annotation.StaticAnnotation { + def this(clazz: Class[T]) = this() +} -- cgit v1.2.3 From 37f1f04142d9ab899655a7de7c80fac66b4405c7 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Fri, 28 Sep 2012 09:22:14 -0400 Subject: add a bit about unicode to scaladoc. --- src/library/scala/StringContext.scala | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'src/library') diff --git a/src/library/scala/StringContext.scala b/src/library/scala/StringContext.scala index 17c1d0d2ba..d9f41f6002 100644 --- a/src/library/scala/StringContext.scala +++ b/src/library/scala/StringContext.scala @@ -97,6 +97,13 @@ case class StringContext(parts: String*) { * * For example, the raw processed string `raw"a\nb"` is equal to the scala string `"a\\nb"`. * + * ''Note:'' Even when using the raw interpolator, Scala will preprocess unicode escapes. + * For example: + * {{{ + * scala> raw"\u0123" + * res0: String = ģ + * }}} + * * @param `args` The arguments to be inserted into the resulting string. * @throws An `IllegalArgumentException` * if the number of `parts` in the enclosing `StringContext` does not exceed -- cgit v1.2.3 From 4a40d83a5a4a357c8eeecb4f1dc3a15533aa76ca Mon Sep 17 00:00:00 2001 From: Simon Ochsenreither Date: Sat, 29 Sep 2012 16:41:11 +0200 Subject: SI-6449 Adds version arg to @deprecated usages (non-compiler sources) --- src/actors/scala/actors/ActorRef.scala | 2 +- src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala | 2 +- src/library/scala/collection/TraversableOnce.scala | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) (limited to 'src/library') diff --git a/src/actors/scala/actors/ActorRef.scala b/src/actors/scala/actors/ActorRef.scala index 5e0ca1554a..cca78b0832 100644 --- a/src/actors/scala/actors/ActorRef.scala +++ b/src/actors/scala/actors/ActorRef.scala @@ -8,7 +8,7 @@ import scala.concurrent.ExecutionContext.Implicits.global /** * Trait used for migration of Scala actors to Akka. */ -@deprecated("ActorRef ought to be used only with the Actor Migration Kit.") +@deprecated("ActorRef ought to be used only with the Actor Migration Kit.", "2.10.0") trait ActorRef { /** diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala index 86bf1f1efd..48624ec28f 100644 --- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala @@ -861,7 +861,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) { inTpl.members.find(_.sym == aSym) } - @deprecated("2.10", "Use findLinkTarget instead!") + @deprecated("Use `findLinkTarget` instead.", "2.10.0") def findTemplate(query: String): Option[DocTemplateImpl] = { assert(modelFinished) docTemplatesCache.values find { (tpl: DocTemplateImpl) => tpl.qualifiedName == query && !packageDropped(tpl) && !tpl.isObject } diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala index d77d278fca..f912304680 100644 --- a/src/library/scala/collection/TraversableOnce.scala +++ b/src/library/scala/collection/TraversableOnce.scala @@ -366,9 +366,9 @@ trait TraversableOnce[+A] extends Any with GenTraversableOnce[A] { object TraversableOnce { - @deprecated("use OnceCanBuildFrom instead") + @deprecated("use OnceCanBuildFrom instead", "2.10.0") def traversableOnceCanBuildFrom[T] = new OnceCanBuildFrom[T] - @deprecated("use MonadOps instead") + @deprecated("use MonadOps instead", "2.10.0") def wrapTraversableOnce[A](trav: TraversableOnce[A]) = new MonadOps(trav) implicit def alternateImplicit[A](trav: TraversableOnce[A]) = new ForceImplicitAmbiguity -- cgit v1.2.3 From b34afb227f0c41ec4cdedf52c553574824473d25 Mon Sep 17 00:00:00 2001 From: Simon Ochsenreither Date: Sat, 29 Sep 2012 16:50:06 +0200 Subject: Fix incomplete version strings (2.10 -> 2.10.0) --- src/actors-migration/scala/actors/migration/StashingActor.scala | 2 +- src/library/scala/annotation/migration.scala | 2 +- src/library/scala/collection/immutable/BitSet.scala | 4 ++-- src/library/scala/collection/immutable/RedBlack.scala | 2 +- src/library/scala/collection/immutable/TreeMap.scala | 2 +- src/library/scala/collection/immutable/TreeSet.scala | 2 +- src/library/scala/testing/Show.scala | 2 +- src/library/scala/util/Either.scala | 2 +- src/library/scala/xml/Elem.scala | 2 +- src/library/scala/xml/Utility.scala | 2 +- 10 files changed, 11 insertions(+), 11 deletions(-) (limited to 'src/library') diff --git a/src/actors-migration/scala/actors/migration/StashingActor.scala b/src/actors-migration/scala/actors/migration/StashingActor.scala index d0a1432e72..2a6351f120 100644 --- a/src/actors-migration/scala/actors/migration/StashingActor.scala +++ b/src/actors-migration/scala/actors/migration/StashingActor.scala @@ -13,7 +13,7 @@ object StashingActor extends Combinators { } } -@deprecated("Scala Actors are being removed from the standard library. Please refer to the migration guide.", "2.10") +@deprecated("Scala Actors are being removed from the standard library. Please refer to the migration guide.", "2.10.0") trait StashingActor extends InternalActor { type Receive = PartialFunction[Any, Unit] diff --git a/src/library/scala/annotation/migration.scala b/src/library/scala/annotation/migration.scala index f60c827620..a55c7006a1 100644 --- a/src/library/scala/annotation/migration.scala +++ b/src/library/scala/annotation/migration.scala @@ -25,6 +25,6 @@ package scala.annotation * @since 2.8 */ private[scala] final class migration(message: String, changedIn: String) extends scala.annotation.StaticAnnotation { - @deprecated("Use the constructor taking two Strings instead.", "2.10") + @deprecated("Use the constructor taking two Strings instead.", "2.10.0") def this(majorVersion: Int, minorVersion: Int, message: String) = this(message, majorVersion + "." + minorVersion) } diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala index 1b676e2d2f..d79e2adbda 100644 --- a/src/library/scala/collection/immutable/BitSet.scala +++ b/src/library/scala/collection/immutable/BitSet.scala @@ -31,7 +31,7 @@ abstract class BitSet extends scala.collection.AbstractSet[Int] with Serializable { override def empty = BitSet.empty - @deprecated("Use BitSet.fromBitMask[NoCopy] instead of fromArray", "2.10") + @deprecated("Use BitSet.fromBitMask[NoCopy] instead of fromArray", "2.10.0") def fromArray(elems: Array[Long]): BitSet = fromBitMaskNoCopy(elems) protected def fromBitMaskNoCopy(elems: Array[Long]): BitSet = BitSet.fromBitMaskNoCopy(elems) @@ -82,7 +82,7 @@ object BitSet extends BitSetFactory[BitSet] { implicit def canBuildFrom: CanBuildFrom[BitSet, Int, BitSet] = bitsetCanBuildFrom /** A bitset containing all the bits in an array */ - @deprecated("Use fromBitMask[NoCopy] instead of fromArray", "2.10") + @deprecated("Use fromBitMask[NoCopy] instead of fromArray", "2.10.0") def fromArray(elems: Array[Long]): BitSet = fromBitMaskNoCopy(elems) /** A bitset containing all the bits in an array */ diff --git a/src/library/scala/collection/immutable/RedBlack.scala b/src/library/scala/collection/immutable/RedBlack.scala index a3ab27f814..77e5a87e73 100644 --- a/src/library/scala/collection/immutable/RedBlack.scala +++ b/src/library/scala/collection/immutable/RedBlack.scala @@ -18,7 +18,7 @@ package immutable * * @since 2.3 */ -@deprecated("use `TreeMap` or `TreeSet` instead", "2.10") +@deprecated("use `TreeMap` or `TreeSet` instead", "2.10.0") @SerialVersionUID(8691885935445612921L) abstract class RedBlack[A] extends Serializable { diff --git a/src/library/scala/collection/immutable/TreeMap.scala b/src/library/scala/collection/immutable/TreeMap.scala index 51bc76efc3..f7a24f3d66 100644 --- a/src/library/scala/collection/immutable/TreeMap.scala +++ b/src/library/scala/collection/immutable/TreeMap.scala @@ -51,7 +51,7 @@ class TreeMap[A, +B] private (tree: RB.Tree[A, B])(implicit val ordering: Orderi with MapLike[A, B, TreeMap[A, B]] with Serializable { - @deprecated("use `ordering.lt` instead", "2.10") + @deprecated("use `ordering.lt` instead", "2.10.0") def isSmaller(x: A, y: A) = ordering.lt(x, y) override protected[this] def newBuilder : Builder[(A, B), TreeMap[A, B]] = diff --git a/src/library/scala/collection/immutable/TreeSet.scala b/src/library/scala/collection/immutable/TreeSet.scala index 697da2bc4b..0fdb16c23b 100644 --- a/src/library/scala/collection/immutable/TreeSet.scala +++ b/src/library/scala/collection/immutable/TreeSet.scala @@ -96,7 +96,7 @@ class TreeSet[A] private (tree: RB.Tree[A, Unit])(implicit val ordering: Orderin override def takeWhile(p: A => Boolean) = take(countWhile(p)) override def span(p: A => Boolean) = splitAt(countWhile(p)) - @deprecated("use `ordering.lt` instead", "2.10") + @deprecated("use `ordering.lt` instead", "2.10.0") def isSmaller(x: A, y: A) = compare(x,y) < 0 def this()(implicit ordering: Ordering[A]) = this(null)(ordering) diff --git a/src/library/scala/testing/Show.scala b/src/library/scala/testing/Show.scala index da1868c7f6..c6c58f5da2 100644 --- a/src/library/scala/testing/Show.scala +++ b/src/library/scala/testing/Show.scala @@ -37,7 +37,7 @@ trait Show { } } - @deprecated("use SymApply instead", "2.10") + @deprecated("use SymApply instead", "2.10.0") def symApply(sym: Symbol): SymApply = new SymApply(sym) /** Apply method with name of given symbol `f` to given arguments and return diff --git a/src/library/scala/util/Either.scala b/src/library/scala/util/Either.scala index f0253eee07..51342eda78 100644 --- a/src/library/scala/util/Either.scala +++ b/src/library/scala/util/Either.scala @@ -221,7 +221,7 @@ object Either { case Right(a) => a } } - @deprecated("use MergeableEither instead", "2.10") + @deprecated("use MergeableEither instead", "2.10.0") def either2mergeable[A](x: Either[A, A]): MergeableEither[A] = new MergeableEither(x) /** diff --git a/src/library/scala/xml/Elem.scala b/src/library/scala/xml/Elem.scala index 2ca1dbfcd0..a92d7859c3 100755 --- a/src/library/scala/xml/Elem.scala +++ b/src/library/scala/xml/Elem.scala @@ -59,7 +59,7 @@ class Elem( val child: Node*) extends Node with Serializable { - @deprecated("This constructor is retained for backward compatibility. Please use the primary constructor, which lets you specify your own preference for `minimizeEmpty`.", "2.10") + @deprecated("This constructor is retained for backward compatibility. Please use the primary constructor, which lets you specify your own preference for `minimizeEmpty`.", "2.10.0") def this(prefix: String, label: String, attributes: MetaData, scope: NamespaceBinding, child: Node*) = { this(prefix, label, attributes, scope, child.isEmpty, child: _*) } diff --git a/src/library/scala/xml/Utility.scala b/src/library/scala/xml/Utility.scala index 50a284d7cd..b390235d59 100755 --- a/src/library/scala/xml/Utility.scala +++ b/src/library/scala/xml/Utility.scala @@ -175,7 +175,7 @@ object Utility extends AnyRef with parsing.TokenTests { * Note that calling this source-compatible method will result in the same old, arguably almost universally unwanted, * behaviour. */ - @deprecated("Please use `serialize` instead and specify a `minimizeTags` parameter", "2.10") + @deprecated("Please use `serialize` instead and specify a `minimizeTags` parameter", "2.10.0") def toXML( x: Node, pscope: NamespaceBinding = TopScope, -- cgit v1.2.3 From a191b3a229c2ec7d7d5d2dd7e3dce2ba95a83c1a Mon Sep 17 00:00:00 2001 From: Paul Phillips Date: Mon, 1 Oct 2012 02:11:26 -0700 Subject: Fix StringContext documentation. It doesn't call "new", as I discovered after some head scratching. --- src/library/scala/StringContext.scala | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'src/library') diff --git a/src/library/scala/StringContext.scala b/src/library/scala/StringContext.scala index d9f41f6002..fb43d56020 100644 --- a/src/library/scala/StringContext.scala +++ b/src/library/scala/StringContext.scala @@ -8,7 +8,7 @@ package scala -/** This class provides the basic mechanism to do String Interpolation. +/** This class provides the basic mechanism to do String Interpolation. * String Interpolation allows users * to embed variable references directly in *processed* string literals. * Here's an example: @@ -26,7 +26,7 @@ package scala * is rewritten to be: * * {{{ - * new StringContext("Hello, ", "").s(name) + * StringContext("Hello, ", "").s(name) * }}} * * By default, this class provides the `raw`, `s` and `f` methods as @@ -36,7 +36,7 @@ package scala * which adds a method to `StringContext`. Here's an example: * {{{ * implicit class JsonHelper(val sc: StringContext) extends AnyVal { - * def json(args: Any*): JSONObject = ... + * def json(args: Any*): JSONObject = ... * } * val x: JSONObject = json"{ a: $a }" * }}} @@ -72,7 +72,7 @@ case class StringContext(parts: String*) { * println(s"Hello, $name") // Hello, James * }}} * In this example, the expression $name is replaced with the `toString` of the - * variable `name`. + * variable `name`. * The `s` interpolator can take the `toString` of any arbitrary expression within * a `${}` block, for example: * {{{ @@ -98,7 +98,7 @@ case class StringContext(parts: String*) { * For example, the raw processed string `raw"a\nb"` is equal to the scala string `"a\\nb"`. * * ''Note:'' Even when using the raw interpolator, Scala will preprocess unicode escapes. - * For example: + * For example: * {{{ * scala> raw"\u0123" * res0: String = ģ @@ -133,7 +133,7 @@ case class StringContext(parts: String*) { * that starts with a formatting specifier, the expression is formatted according to that * specifier. All specifiers allowed in Java format strings are handled, and in the same * way they are treated in Java. - * + * * For example: * {{{ * val height = 1.9d -- cgit v1.2.3 From ab7857b7b2c122012bedb6e173753d41c1063efa Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Tue, 2 Oct 2012 11:49:05 +0200 Subject: Improved the `scala.language` documentation Also corrected the links in the library rootdoc. **Note: We need to fast track this commit so it reaches master in the next 12 hours, before we generate the next nightly docs.** Review by @odersky --- .../scala/tools/nsc/doc/html/HtmlPage.scala | 2 +- .../nsc/doc/model/comment/CommentFactory.scala | 2 +- src/library/rootdoc.txt | 21 +++--- src/library/scala/language.scala | 79 ++++++++++++++++++---- 4 files changed, 77 insertions(+), 27 deletions(-) (limited to 'src/library') diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala index 2c719e5d70..b47e9f5784 100644 --- a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala +++ b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala @@ -117,7 +117,7 @@ abstract class HtmlPage extends Page { thisPage => case Underline(in) => { inlineToHtml(in) } case Superscript(in) => { inlineToHtml(in) } case Subscript(in) => { inlineToHtml(in) } - case Link(raw, title) => { inlineToHtml(title) } + case Link(raw, title) => { inlineToHtml(title) } case Monospace(in) => { inlineToHtml(in) } case Text(text) => scala.xml.Text(text) case Summary(in) => inlineToHtml(in) diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala index 1baa7f9831..924ebb8a3b 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala @@ -147,7 +147,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory with Member case (group, body) => try { body match { - case Body(List(Paragraph(Chain(List(Summary(Text(prio))))))) => List(group -> prio.toInt) + case Body(List(Paragraph(Chain(List(Summary(Text(prio))))))) => List(group -> prio.trim.toInt) case _ => List() } } catch { diff --git a/src/library/rootdoc.txt b/src/library/rootdoc.txt index da27a0084b..0722d808bf 100644 --- a/src/library/rootdoc.txt +++ b/src/library/rootdoc.txt @@ -4,24 +4,25 @@ This is the documentation for the Scala standard library. The [[scala]] package contains core types. -scala.[[scala.collection]] and its subpackages contain a collections framework with higher-order functions for manipulation. Both [[scala.collection.immutable]] and [[scala.collection.mutable]] data structures are available, with immutable as the default. The [[scala.collection.parallel]] collections provide automatic parallel operation. +[[scala.collection `scala.collection`]] and its subpackages contain a collections framework with higher-order functions for manipulation. Both [[scala.collection.immutable `scala.collection.immutable`]] and [[scala.collection.mutable `scala.collection.mutable`]] data structures are available, with immutable as the default. The [[scala.collection.parallel `scala.collection.parallel`]] collections provide automatic parallel operation. Other important packages include: - - scala.[[scala.actors]] - Concurrency framework inspired by Erlang. - - scala.[[scala.io]] - Input and output. - - scala.[[scala.math]] - Basic math functions and additional numeric types. - - scala.[[scala.sys]] - Interaction with other processes and the operating system. - - scala.util.[[scala.util.matching]] - Pattern matching in text using regular expressions. - - scala.util.parsing.[[scala.util.parsing.combinator]] - Composable combinators for parsing. - - scala.[[scala.xml]] - XML parsing, manipulation, and serialization. + - [[scala.actors `scala.actors`]] - Concurrency framework inspired by Erlang. + - [[scala.io `scala.io`]] - Input and output. + - [[scala.math `scala.math`]] - Basic math functions and additional numeric types. + - [[scala.sys `scala.sys`]] - Interaction with other processes and the operating system. + - [[scala.util.matching `scala.util.matching`]] - Pattern matching in text using regular expressions. + - [[scala.util.parsing.combinator `scala.util.parsing.combinator`]] - Composable combinators for parsing. + - [[scala.xml `scala.xml`]] - XML parsing, manipulation, and serialization. Many other packages exist. See the complete list on the left. == Automatic imports == -Identifiers in the scala package and the [[scala.Predef]] object are always in scope by default. +Identifiers in the scala package and the [[scala.Predef `scala.Predef`]] object are always in scope by default. -Some of these identifiers are type aliases provided as shortcuts to commonly used classes. For example, `List` is an alias for scala.collection.immutable.[[scala.collection.immutable.List]]. +Some of these identifiers are type aliases provided as shortcuts to commonly used classes. For example, `List` is an alias for +[[scala.collection.immutable.List `scala.collection.immutable.List`]]. Other aliases refer to classes provided by the underlying platform. For example, on the JVM, `String` is an alias for `java.lang.String`. diff --git a/src/library/scala/language.scala b/src/library/scala/language.scala index 297f344f65..c638f531bb 100644 --- a/src/library/scala/language.scala +++ b/src/library/scala/language.scala @@ -1,5 +1,28 @@ package scala +/** + * The `scala.language` object controls the language features available to the programmer, as proposed in the + * [[https://docs.google.com/document/d/1nlkvpoIRkx7at1qJEZafJwthZ3GeIklTFhqmXMvTX9Q/edit '''SIP-18 document''']]. + * + * Each of these features has to be explicitly imported into the current scope to become available: + * {{{ + * import language.postfixOps // or language._ + * List(1, 2, 3) reverse + * }}} + * + * The language features are: + * - [[dynamics `dynamics`]] enables defining calls rewriting using the [[scala.Dynamic `Dynamic`]] trait + * - [[postfixOps `postfixOps`]] enables postfix operators + * - [[reflectiveCalls `reflectiveCalls`]] enables using structural types + * - [[implicitConversions `implicitConversions`]] enables defining implicit methods and members + * - [[higherKinds `higherKinds`]] enables writing higher-kinded types + * - [[existentials `existentials`]] enables writing existential types + * - [[experimental `experimental`]] contains newer features that have not yet been tested in production + * + * @groupname production Language Features + * @groupname experimental Experimental Language Features + * @groupprio experimental 10 + */ object language { import languageFeature._ @@ -10,21 +33,25 @@ object language { * selection of existing subclasses of trait Dynamic are unaffected; * they can be used anywhere. * - * _Why introduce the feature?_ To enable flexible DSLs and convenient interfacing + * '''Why introduce the feature?''' To enable flexible DSLs and convenient interfacing * with dynamic languages. * - * _Why control it?_ Dynamic member selection can undermine static checkability + * '''Why control it?''' Dynamic member selection can undermine static checkability * of programs. Furthermore, dynamic member selection often relies on reflection, * which is not available on all platforms. + * + * @group production */ implicit lazy val dynamics: dynamics = languageFeature.dynamics /** Only where enabled, postfix operator notation `(expr op)` will be allowed. * - * _Why keep the feature?_ Several DSLs written in Scala need the notation. + * '''Why keep the feature?''' Several DSLs written in Scala need the notation. * - * _Why control it?_ Postfix operators interact poorly with semicolon inference. + * '''Why control it?''' Postfix operators interact poorly with semicolon inference. * Most programmers avoid them for this reason. + * + * @group production */ implicit lazy val postfixOps: postfixOps = languageFeature.postfixOps @@ -34,13 +61,15 @@ object language { * not override any member in `Parents`. To access one of these members, a * reflective call is needed. * - * _Why keep the feature?_ Structural types provide great flexibility because + * '''Why keep the feature?''' Structural types provide great flexibility because * they avoid the need to define inheritance hierarchies a priori. Besides, * their definition falls out quite naturally from Scala’s concept of type refinement. * - * _Why control it?+ Reflection is not available on all platforms. Popular tools + * '''Why control it?''' Reflection is not available on all platforms. Popular tools * such as ProGuard have problems dealing with it. Even where reflection is available, * reflective dispatch can lead to surprising performance degradations. + * + * @group production */ implicit lazy val reflectiveCalls: reflectiveCalls = languageFeature.reflectiveCalls @@ -49,32 +78,36 @@ object language { * or an implicit method that has in its first parameter section a single, * non-implicit parameter. Examples: * + * {{{ * implicit def stringToInt(s: String): Int = s.length * implicit val conv = (s: String) => s.length - * implicit def listToX(xs: List[T])(implicit f: T => X): X = … + * implicit def listToX(xs: List[T])(implicit f: T => X): X = ... + * }}} * * implicit values of other types are not affected, and neither are implicit * classes. * - * _Why keep the feature?_ Implicit conversions are central to many aspects + * '''Why keep the feature?''' Implicit conversions are central to many aspects * of Scala’s core libraries. * - * _Why control it?_ Implicit conversions are known to cause many pitfalls + * '''Why control it?''' Implicit conversions are known to cause many pitfalls * if over-used. And there is a tendency to over-use them because they look * very powerful and their effects seem to be easy to understand. Also, in * most situations using implicit parameters leads to a better design than * implicit conversions. + * + * @group production */ implicit lazy val implicitConversions: implicitConversions = languageFeature.implicitConversions /** Only where this flag is enabled, higher-kinded types can be written. * - * _Why keep the feature?_ Higher-kinded types enable the definition of very general + * '''Why keep the feature?''' Higher-kinded types enable the definition of very general * abstractions such as functor, monad, or arrow. A significant set of advanced * libraries relies on them. Higher-kinded types are also at the core of the * scala-virtualized effort to produce high-performance parallel DSLs through staging. * - * _Why control it?_ Higher kinded types in Scala lead to a Turing-complete + * '''Why control it?''' Higher kinded types in Scala lead to a Turing-complete * type system, where compiler termination is no longer guaranteed. They tend * to be useful mostly for type-level computation and for highly generic design * patterns. The level of abstraction implied by these design patterns is often @@ -85,6 +118,8 @@ object language { * higher-kinded types will change in future versions of Scala. So an explicit * enabling also serves as a warning that code involving higher-kinded types * might have to be slightly revised in the future. + * + * @group production */ implicit lazy val higherKinds: higherKinds = languageFeature.higherKinds @@ -93,17 +128,31 @@ object language { * types of methods. Existential types with wildcard type syntax such as `List[_]`, * or `Map[String, _]` are not affected. * - * _Why keep the feature?_ Existential types are needed to make sense of Java’s wildcard + * '''Why keep the feature?''' Existential types are needed to make sense of Java’s wildcard * types and raw types and the erased types of run-time values. * - * Why control it? Having complex existential types in a code base usually makes + * '''Why control it?''' Having complex existential types in a code base usually makes * application code very brittle, with a tendency to produce type errors with * obscure error messages. Therefore, going overboard with existential types * is generally perceived not to be a good idea. Also, complicated existential types * might be no longer supported in a future simplification of the language. + * + * @group production */ implicit lazy val existentials: existentials = languageFeature.existentials + /** The experimental object contains features that have been recently added but have not + * been thoroughly tested in production yet. + * + * Experimental features '''may undergo API changes''' in future releases, so production + * code should not rely on them. + * + * Programmers are encouraged to try out experimental features and + * [[http://issues.scala-lang.org report any bugs or API inconsistencies]] + * they encounter so they can be improved in future releases. + * + * @group experimental + */ object experimental { import languageFeature.experimental._ @@ -111,12 +160,12 @@ object language { /** Where enabled, macro definitions are allowed. Macro implementations and * macro applications are unaffected; they can be used anywhere. * - * _Why introduce the feature?_ Macros promise to make the language more regular, + * '''Why introduce the feature?''' Macros promise to make the language more regular, * replacing ad-hoc language constructs with a general powerful abstraction * capability that can express them. Macros are also a more disciplined and * powerful replacement for compiler plugins. * - * _Why control it?_ For their very power, macros can lead to code that is hard + * '''Why control it?''' For their very power, macros can lead to code that is hard * to debug and understand. */ implicit lazy val macros: macros = languageFeature.experimental.macros -- cgit v1.2.3