Apply suggestions from code review

improve documentation based on suggestions

Co-authored-by: odersky <[email protected]>

docs/_docs/reference/experimental/runtimeChecked.md

@@ -4,13 +4,13 @@ title: "The runtimeChecked method"
 nightlyOf: https://docs.scala-lang.org/scala3/reference/experimental/runtimeChecked.html
 ---
 
-The `runtimeChecked` method is an extension method, defined in `scala.Predef`. It can be called on any expression. An expression marked as `runtimeChecked` is exempt from certain static checks in the compiler, for example pattern match exhaustivity. It is intended to replace `: @unchecked` type ascription in these cases.
+The `runtimeChecked` method is an extension method, defined in `scala.Predef`. It can be called on any expression. An expression ending in `.runtimeChecked` is exempt from certain static checks in the compiler, for example pattern match exhaustivity. The idiom is intended to replace a `: @unchecked` type ascription in these cases.
 
 ## Example
 
 A common use case for `runtimeChecked` is to assert that a pattern will always match, either for convenience, or because there is a known invariant that the types can not express.
 
-e.g. looking up an expected entry in a dynamically loaded dictionary-like structure
+E.g. looking up an expected entry in a dynamically loaded dictionary-like structure:
 ```scala
 // example 1
 trait AppConfig:
@@ -35,7 +35,7 @@ weekDay.runtimeChecked match
   case None =>
 ```
 
-In both of these cases, without `runtimeChecked` then there would either be an error (example 1), or a warning (example 2), because statically, the compiler knows that there could be other cases at runtime - so is right to caution the programmer.
+In both of these cases, without `runtimeChecked` there would either be an error (example 1), or a warning (example 2), because statically, the compiler knows that there could be other cases at runtime - so is right to caution the programmer.
 
 ```scala
 // warning in example 2 when we don't add `.runtimeChecked`.
@@ -76,18 +76,18 @@ val res1: Int = 1
 
 ## Specification
 
-We add a new annotation `scala.internal.RuntimeChecked`, this is part of the standard Scala 3 library. A programmer is not expected to use this annotation directly.
+We add a new annotation `scala.internal.RuntimeChecked` as a part of the standard Scala 3 library. A programmer is not expected to use this annotation directly.
 
 ```scala
 package scala.annotation.internal
 
 final class RuntimeChecked extends Annotation
 ```
 
-Any term that is the scrutinee of a pattern match, that has a type annotated with `RuntimeChecked`, is exempt from pattern match exhaustivity checking.
+Any term that is the scrutinee of a pattern match, and that has a type annotated with `RuntimeChecked`, is exempt from pattern match exhaustivity checking.
 
 
-The user facing API is provided by a new extension method `scala.Predef.runtimeChecked`, qualified for any value:
+The user facing API is augmented with a new extension method `scala.Predef.runtimeChecked`, qualified for any value:
 ```scala
 package scala
 
@@ -124,9 +124,9 @@ As an escape hatch in 3.2 we recommended to use a type ascription of `: @uncheck
   |which may result in a MatchError at runtime.
 ```
 
-We suggest that `: @unchecked` is syntactically awkward, and also a misnomer - in fact in this case the the pattern is fully checked, but the necessary checks occur at runtime. The `runtimeChecked` method is then a successor to `@unchecked` for this purpose.
+However, `: @unchecked` is syntactically awkward, and is also a misnomer - in fact in this case the the pattern _is_ fully checked, but the necessary checks occur at runtime. The `runtimeChecked` method is intended to replace `@unchecked` for this purpose. 
 
-We propose that `@unchecked` will still be necessary for silencing warnings on unsound type tests.
+The `@unchecked` annotation is still retained for silencing warnings on unsound type tests.
 
 ### Restoring Scala 2.13 semantics with runtimeChecked