Merge pull request #11451 from ShapelessCat/fix-and-imrpove-extension-methods-docs

Update and fix the generic extension methods document and the RC1 release blog

Author: anatoliykmetyuk

docs/blog/_posts/2021-02-17-scala3-rc1.md

@@ -8,12 +8,14 @@ date: 2021-02-17
 
 Greetings from the Scala 3 team! We are delighted to announce the first release candidate of the stable version of Scala 3 – Scala 3.0.0-RC1.
 
-This release brings some last-minute polishings, clean-ups and changes before the big release. There were a few language changes to improve the user experience, as well as the polishings of the metaprogramming framework. We have also worked on the issues that had to be fixed before the stable release.
+This release brings some last-minute polishings, clean-ups and changes before the big release. There were a few language changes to improve the user experience,
+as well as the polishings of the metaprogramming framework. We have also worked on the issues that had to be fixed before the stable release.
 
 Overall, more than [400 PRs](https://github.com/lampepfl/dotty/pulls?q=is%3Apr+is%3Aclosed+closed%3A%3E2020-12-02+sort%3Acomments-desc) were merged after the M3 release and until today! Read more below!
 
 <!--more-->
-# Allow secondary type parameter list in extension methods
+## Allow secondary type parameter list in extension methods
+
 Type parameters on extensions can now be combined with type parameters on the methods themselves. E.g.:
 
 ```scala
@@ -27,6 +29,7 @@ Type arguments matching method type parameters are passed as usual:
 ```scala
 List("a", "bb", "ccc").sumBy[Int](_.length)
 ```
+
 By contrast, type arguments matching type parameters following `extension` can be passed
 only if the method is referenced as a non-extension method:
 
@@ -42,7 +45,8 @@ sumBy[String](List("a", "bb", "ccc"))[Int](_.length)
 
 For discussion, see [PR #10940](https://github.com/lampepfl/dotty/pull/10940). For more information about the extension methods, see [documentation](https://dotty.epfl.ch/docs/reference/contextual/extension-methods.html).
 
-# New `import` syntax
+## New `import` syntax
+
 The following are the changes to the `import` syntax made in this release.
 
 Wildcard import `_` is replaced by `*`. The motivation is that the majority of other languages use `*`. For example:
@@ -60,10 +64,12 @@ import NumPy as np
 
 For the details and discussion, see [PR #11244](https://github.com/lampepfl/dotty/pull/11244). Read more about this change in the [documentation](https://dotty.epfl.ch/docs/reference/changed-features/imports.html).
 
-# Use `*` for vararg splices.
+## Use `*` for vararg splices
+
 [PR #11240](https://github.com/lampepfl/dotty/pull/11240) changed the syntax of vararg splices in patterns and function arguments. The new syntax uses a postfix `*`, instead of `: _*`, analogously to how a vararg parameter is declared.
 
-# Use `uninitialized` for wildcard initializers
+## Use `uninitialized` for wildcard initializers
+
 An obscure use of `_` occurs in var definitions:
 
 ```scala
@@ -84,7 +90,8 @@ This way expresses the intent of the idiom in a more verbose and easy to read wa
 
 For discussion, see [PR #11231](https://github.com/lampepfl/dotty/pull/11231), and the [documentation](https://dotty.epfl.ch/docs/reference/dropped-features/wildcard-init.html) is available on our website.
 
-# Eta-expand companion object if functions are expected
+## Eta-expand companion object if functions are expected
+
 Starting from RC1, we no longer generate a function parent for companions of case classes. Which means, for example, that given `case class Foo(x: Int)`, you won't be able to use `Foo` in a position where a function is expected:
 
 ```scala
@@ -104,18 +111,26 @@ Results in:
 
 As the warning suggests, now you should write `Foo.apply` instead of `Foo`. See [Issue #6190](https://github.com/lampepfl/dotty/issues/6190) and [PR #7207](https://github.com/lampepfl/dotty/pull/7207) for discussion.
 
-# Settling on `scaladoc` as the documentation tool
-We have settled on using the well-known `scaladoc` as a name for the documentation tool for Scala 3 (known previously as `scala3doc`).. The obsolete `dotty-doc` (or `scala3-doc`) is removed in RC1. We have also removed all the Kotlin dependencies (Dokka, etc.) from scaladoc. For details, see [PR #11349](https://github.com/lampepfl/dotty/pull/11349). To read more about `scaladoc`, see [documentation](https://dotty.epfl.ch/docs/usage/scaladoc/index.html)
+## Settling on `scaladoc` as the documentation tool
+
+We have settled on using the well-known `scaladoc` as a name for the documentation tool for Scala 3 (known previously as `scala3doc`).
+The obsolete `dotty-doc` (or `scala3-doc`) is removed in RC1. We have also removed all the Kotlin dependencies (Dokka, etc.) from scaladoc.
+For details, see [PR #11349](https://github.com/lampepfl/dotty/pull/11349). To read more about `scaladoc`, see [documentation](https://dotty.epfl.ch/docs/usage/scaladoc/index.html)
+
+## Use `future` and `future-migration` to specify language versions after 3.0 in `-source`
 
-# Use `future` and `future-migration` to specify language versions after 3.0 in `-source`
 [PR #11355](https://github.com/lampepfl/dotty/pull/11355) changes the `-source` specifier for the Scala version(s) after 3.0 from `3.1` to `future`. I.e. it is now
-`-source future` and `-source future-migration` instead of `-source 3.1` and `-source 3.1-migration`. Language imports are changed analogously. The reason for the change is that we want to keep the possibility open to ship a `3.1` version that does not yet contain all the changes enabled under `-source future`.
+`-source future` and `-source future-migration` instead of `-source 3.1` and `-source 3.1-migration`. Language imports are changed analogously. The reason for the change is that
+we want to keep the possibility open to ship a `3.1` version that does not yet contain all the changes enabled under `-source future`.
+
+## Other language changes
 
-# Other language changes
 - Warn when matching against an opaque type [#10664](https://github.com/lampepfl/dotty/pull/10664)
-- Fix [#8634](https://github.com/lampepfl/dotty/issues/8634): Support -release option [#10746](https://github.com/lampepfl/dotty/pull/10746) – the same way Scala 2 does. This setting allows you to specify a version of the Java platform (8, 9 etc) and compile the code with classes specific to the that Java platform, and emit the bytecode for that version.
+- Fix [#8634](https://github.com/lampepfl/dotty/issues/8634): Support -release option [#10746](https://github.com/lampepfl/dotty/pull/10746) – the same way Scala 2 does.
+  This setting allows you to specify a version of the Java platform (8, 9 etc) and compile the code with classes specific to the that Java platform, and emit the bytecode for that version.
+
+## Metaprogramming changes
 
-# Metaprogramming changes
 A lot of work has been done on the metaprogramming side of things. Mostly we are cleaning up and polishing the API to prepare it for the stable release. The following are the important metaprogramming changes that took place:
 
 - Add `scala.quoted.Expr.unapply` as dual of `Expr.apply` [#10580](https://github.com/lampepfl/dotty/pull/10580)
@@ -132,13 +147,14 @@ A lot of work has been done on the metaprogramming side of things. Mostly we are
 - Rename `Not` to `NotGiven` to make its purpose clearer [#10720](https://github.com/lampepfl/dotty/pull/10720)
 - Fix [#10709](https://github.com/lampepfl/dotty/issues/10709): Add missing level check before inlining [#10781](https://github.com/lampepfl/dotty/pull/10781)
 
-# Let us know what you think!
+## Let us know what you think!
+
 If you have questions or any sort of feedback, feel free to send us a message on our
 [Gitter channel](https://gitter.im/lampepfl/dotty). If you encounter a bug, please
 [open an issue on GitHub](https://github.com/lampepfl/dotty/issues/new).
 
-
 ## Contributors
+
 Thank you to all the contributors who made this release possible 🎉
 
 According to `git shortlog -sn --no-merges 3.0.0-M3..3.0.0-RC1` these are:

docs/docs/reference/contextual/extension-methods.md

@@ -89,13 +89,13 @@ List("a", "bb", "ccc").sumBy[Int](_.length)
 ```
 
 By contrast, type arguments matching type parameters following `extension` can be passed
-only if the method is referenced as a regular method:
+only if the method is referenced as a non-extension method:
 
 ```scala
 sumBy[String](List("a", "bb", "ccc"))(_.length)
 ```
 
-or, passing, both type arguments
+Or, when passing both type arguments:
 
 ```scala
 sumBy[String](List("a", "bb", "ccc"))[Int](_.length)