Adjust documentation to various functions

* Adjust `exit()` documentation to mention `finally` and to further
  emphasize that calling `exit()` does not pass Go and does not
  collect $200.

* Adjust `DateTime.difference` documentation to clarify the sign of
  the returned `Duration`.  Fixes #36347.

* Adjust `String.lastIndexOf` documentation to clarify what is
  returned.  Fixes #41893.

Change-Id: I6ed91e8c79a647928ced7e8f0268a62ed92fbd4e
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/149494
Reviewed-by: Jonas Termansen <[email protected]>
Commit-Queue: Jonas Termansen <[email protected]>

Author: jamesderlin

pkg/dev_compiler/tool/dartdevc_nnbd_sdk_error_golden.txt

@@ -1,8 +1,8 @@
-ERROR|COMPILE_TIME_ERROR|CONST_CONSTRUCTOR_THROWS_EXCEPTION|lib/core/core.dart|3719|5|94|Const constructors can't throw exceptions.
-ERROR|COMPILE_TIME_ERROR|CONST_CONSTRUCTOR_THROWS_EXCEPTION|lib/core/core.dart|7909|5|97|Const constructors can't throw exceptions.
+ERROR|COMPILE_TIME_ERROR|CONST_CONSTRUCTOR_THROWS_EXCEPTION|lib/core/core.dart|3722|5|94|Const constructors can't throw exceptions.
+ERROR|COMPILE_TIME_ERROR|CONST_CONSTRUCTOR_THROWS_EXCEPTION|lib/core/core.dart|7912|5|97|Const constructors can't throw exceptions.
 ERROR|COMPILE_TIME_ERROR|CONST_CONSTRUCTOR_THROWS_EXCEPTION|lib/core/core.dart|940|5|95|Const constructors can't throw exceptions.
 ERROR|COMPILE_TIME_ERROR|CONST_CONSTRUCTOR_THROWS_EXCEPTION|lib/core/core.dart|973|5|94|Const constructors can't throw exceptions.
-ERROR|SYNTACTIC_ERROR|CONST_FACTORY|lib/core/core.dart|3717|3|5|Only redirecting factory constructors can be declared to be 'const'.
-ERROR|SYNTACTIC_ERROR|CONST_FACTORY|lib/core/core.dart|7907|3|5|Only redirecting factory constructors can be declared to be 'const'.
+ERROR|SYNTACTIC_ERROR|CONST_FACTORY|lib/core/core.dart|3720|3|5|Only redirecting factory constructors can be declared to be 'const'.
+ERROR|SYNTACTIC_ERROR|CONST_FACTORY|lib/core/core.dart|7910|3|5|Only redirecting factory constructors can be declared to be 'const'.
 ERROR|SYNTACTIC_ERROR|CONST_FACTORY|lib/core/core.dart|938|3|5|Only redirecting factory constructors can be declared to be 'const'.
 ERROR|SYNTACTIC_ERROR|CONST_FACTORY|lib/core/core.dart|971|3|5|Only redirecting factory constructors can be declared to be 'const'.

sdk/lib/core/date_time.dart

@@ -653,7 +653,10 @@ class DateTime implements Comparable<DateTime> {
   external DateTime subtract(Duration duration);
 
   /**
-   * Returns a [Duration] with the difference between [this] and [other].
+   * Returns a [Duration] with the difference when subtracting [other] from
+   * [this].
+   *
+   * The returned [Duration] will be negative if [other] occurs after [this].
    *
    * ```
    * var berlinWallFell = new DateTime.utc(1989, DateTime.november, 9);
@@ -865,8 +868,8 @@ class DateTime implements Comparable<DateTime> {
    * timezone ::= 'z' | 'Z' | sign digit{2} timezonemins_opt
    * timezonemins_opt ::= <empty> | colon_opt digit{2}
    */
-  static final RegExp _parseFormat = RegExp(
-      r'^([+-]?\d{4,6})-?(\d\d)-?(\d\d)' // Day part.
-      r'(?:[ T](\d\d)(?::?(\d\d)(?::?(\d\d)(?:[.,](\d+))?)?)?' // Time part.
-      r'( ?[zZ]| ?([-+])(\d\d)(?::?(\d\d))?)?)?$'); // Timezone part.
+  static final RegExp _parseFormat =
+      RegExp(r'^([+-]?\d{4,6})-?(\d\d)-?(\d\d)' // Day part.
+          r'(?:[ T](\d\d)(?::?(\d\d)(?::?(\d\d)(?:[.,](\d+))?)?)?' // Time part.
+          r'( ?[zZ]| ?([-+])(\d\d)(?::?(\d\d))?)?)?$'); // Timezone part.
 }

sdk/lib/core/string.dart

@@ -295,16 +295,16 @@ abstract class String implements Comparable<String>, Pattern {
   int indexOf(Pattern pattern, [int start]);
 
   /**
-   * Returns the position of the last match [pattern] in this string, searching
-   * backward starting at [start], inclusive:
+   * Returns the starting position of the last match [pattern] in this string,
+   * searching backward starting at [start], inclusive:
    *
    *     var string = 'Dartisans';
    *     string.lastIndexOf('a');                    // 6
-   *     string.lastIndexOf(new RegExp(r'a(r|n)'));  // 6
+   *     string.lastIndexOf(RegExp(r'a(r|n)'));      // 6
    *
    * Returns -1 if [pattern] could not be found in this string.
    *
-   *     string.lastIndexOf(new RegExp(r'DART'));    // -1
+   *     string.lastIndexOf(RegExp(r'DART'));        // -1
    *
    * The [start] must be non-negative and not greater than [length].
    */

sdk/lib/io/process.dart

@@ -20,8 +20,8 @@ class _ProcessUtils {
 /**
  * Exit the Dart VM process immediately with the given exit code.
  *
- * This does not wait for any asynchronous operations to terminate. Using
- * [exit] is therefore very likely to lose data.
+ * This does not wait for any asynchronous operations to terminate nor execute
+ * `finally` blocks. Using [exit] is therefore very likely to lose data.
  *
  * While debugging, the VM will not respect the `--pause-isolates-on-exit`
  * flag if [exit] is called as invoking this method causes the Dart VM

sdk_nnbd/lib/core/date_time.dart

@@ -653,7 +653,10 @@ class DateTime implements Comparable<DateTime> {
   external DateTime subtract(Duration duration);
 
   /**
-   * Returns a [Duration] with the difference between [this] and [other].
+   * Returns a [Duration] with the difference when subtracting [other] from
+   * [this].
+   *
+   * The returned [Duration] will be negative if [other] occurs after [this].
    *
    * ```
    * var berlinWallFell = new DateTime.utc(1989, DateTime.november, 9);
@@ -865,8 +868,8 @@ class DateTime implements Comparable<DateTime> {
    * timezone ::= 'z' | 'Z' | sign digit{2} timezonemins_opt
    * timezonemins_opt ::= <empty> | colon_opt digit{2}
    */
-  static final RegExp _parseFormat = RegExp(
-      r'^([+-]?\d{4,6})-?(\d\d)-?(\d\d)' // Day part.
-      r'(?:[ T](\d\d)(?::?(\d\d)(?::?(\d\d)(?:[.,](\d+))?)?)?' // Time part.
-      r'( ?[zZ]| ?([-+])(\d\d)(?::?(\d\d))?)?)?$'); // Timezone part.
+  static final RegExp _parseFormat =
+      RegExp(r'^([+-]?\d{4,6})-?(\d\d)-?(\d\d)' // Day part.
+          r'(?:[ T](\d\d)(?::?(\d\d)(?::?(\d\d)(?:[.,](\d+))?)?)?' // Time part.
+          r'( ?[zZ]| ?([-+])(\d\d)(?::?(\d\d))?)?)?$'); // Timezone part.
 }

sdk_nnbd/lib/core/string.dart

@@ -293,16 +293,16 @@ abstract class String implements Comparable<String>, Pattern {
   int indexOf(Pattern pattern, [int start = 0]);
 
   /**
-   * Returns the position of the last match [pattern] in this string, searching
-   * backward starting at [start], inclusive:
+   * Returns the starting position of the last match [pattern] in this string,
+   * searching backward starting at [start], inclusive:
    *
    *     var string = 'Dartisans';
    *     string.lastIndexOf('a');                    // 6
-   *     string.lastIndexOf(new RegExp(r'a(r|n)'));  // 6
+   *     string.lastIndexOf(RegExp(r'a(r|n)'));      // 6
    *
    * Returns -1 if [pattern] could not be found in this string.
    *
-   *     string.lastIndexOf(new RegExp(r'DART'));    // -1
+   *     string.lastIndexOf(RegExp(r'DART'));        // -1
    *
    * If [start] is omitted, search starts from the end of the string.
    * If supplied, [start] must be non-negative and not greater than [length].

sdk_nnbd/lib/io/process.dart

@@ -18,8 +18,8 @@ class _ProcessUtils {
 /**
  * Exit the Dart VM process immediately with the given exit code.
  *
- * This does not wait for any asynchronous operations to terminate. Using
- * [exit] is therefore very likely to lose data.
+ * This does not wait for any asynchronous operations to terminate nor execute
+ * `finally` blocks. Using [exit] is therefore very likely to lose data.
  *
  * While debugging, the VM will not respect the `--pause-isolates-on-exit`
  * flag if [exit] is called as invoking this method causes the Dart VM