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