Improve listToString and setToString documentation. Fixes #26529

Bug: #26529
Change-Id: I4e2994dd39c676c2136c82d3e5dd9f45a8b154ce
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/82784
Commit-Queue: Samuel Rawlins <srawlins@google.com>
Reviewed-by: Lasse R.H. Nielsen <lrn@google.com>

runtime/observatory/tests/service/step_through_mixin_from_sdk_test.dart

@@ -35,19 +35,19 @@ List<String> stops = [];
 List<String> expected = [
   "$file:${LINE + 0}:17", // on "Foo" (in "new Foo()")
   "$file:${LINE + 1}:11", // on "="
-  "list.dart:101:24", // on parameter to "contains"
-  "list.dart:102:23", // on "length" in "this.length"
-  "list.dart:103:16", // on "=" in "i = 0"
-  "list.dart:103:23", // on "<" in "i < length"
-  "list.dart:104:15", // on "[" in "this[i]"
+  "list.dart:105:24", // on parameter to "contains"
+  "list.dart:106:23", // on "length" in "this.length"
+  "list.dart:107:16", // on "=" in "i = 0"
+  "list.dart:107:23", // on "<" in "i < length"
+  "list.dart:108:15", // on "[" in "this[i]"
   "$file:${LINE + 13}:23", // on parameter in "operator []"
   "$file:${LINE + 14}:5", // on "return"
-  "list.dart:104:19", // on "=="
-  "list.dart:105:26", // on "length" in "this.length"
-  "list.dart:105:18", // on "!="
-  "list.dart:103:34", // on "++" in "i++"
-  "list.dart:103:23", // on "<" in "i < length"
-  "list.dart:109:5", // on "return"
+  "list.dart:108:19", // on "=="
+  "list.dart:109:26", // on "length" in "this.length"
+  "list.dart:109:18", // on "!="
+  "list.dart:107:34", // on "++" in "i++"
+  "list.dart:107:23", // on "<" in "i < length"
+  "list.dart:113:5", // on "return"
   "$file:${LINE + 4}:5", // on "print"
   "$file:${LINE + 6}:1" // on ending '}'
 ];

sdk/lib/collection/list.dart

@@ -21,7 +21,11 @@ part of dart.collection;
 /// to the growable list, or, preferably, use `DelegatingList` from
 /// "package:collection/wrappers.dart" instead.
 abstract class ListBase<E> extends Object with ListMixin<E> {
-  /// Convert a `List` to a string as `[each, element, as, string]`.
+  /// Converts a [List] to a [String].
+  ///
+  /// Converts [list] to a string by converting each element to a string (by
+  /// calling [Object.toString]), joining them with ", ", and wrapping the
+  /// result in "[" and "]".
   ///
   /// Handles circular references where converting one of the elements
   /// to a string ends up converting [list] to a string again.

sdk/lib/collection/set.dart

@@ -299,7 +299,11 @@ abstract class SetMixin<E> implements Set<E> {
 /// `clear` in constant time. The default implementation works by removing every
 /// element.
 abstract class SetBase<E> extends Object with SetMixin<E> {
-  /// Convert a `Set` to a string as `{each, element, as, string}`.
+  /// Converts a [Set] to a [String].
+  ///
+  /// Converts [set] to a string by converting each element to a string (by
+  /// calling [Object.toString]), joining them with ", ", and wrapping the
+  /// result in "{" and "}".
   ///
   /// Handles circular references where converting one of the elements
   /// to a string ends up converting [set] to a string again.

sdk_nnbd/lib/collection/list.dart

@@ -23,7 +23,11 @@ part of dart.collection;
 /// to the growable list, or, preferably, use `DelegatingList` from
 /// "package:collection/wrappers.dart" instead.
 abstract class ListBase<E> extends Object with ListMixin<E> {
-  /// Convert a `List` to a string as `[each, element, as, string]`.
+  /// Converts a [List] to a [String].
+  ///
+  /// Converts [list] to a string by converting each element to a string (by
+  /// calling [Object.toString]), joining them with ", ", and wrapping the
+  /// result in "[" and "]".
   ///
   /// Handles circular references where converting one of the elements
   /// to a string ends up converting [list] to a string again.

sdk_nnbd/lib/collection/set.dart

@@ -301,7 +301,11 @@ abstract class SetMixin<E> implements Set<E> {
 /// `clear` in constant time. The default implementation works by removing every
 /// element.
 abstract class SetBase<E> extends Object with SetMixin<E> {
-  /// Convert a `Set` to a string as `{each, element, as, string}`.
+  /// Converts a [Set] to a [String].
+  ///
+  /// Converts [set] to a string by converting each element to a string (by
+  /// calling [Object.toString]), joining them with ", ", and wrapping the
+  /// result in "{" and "}".
   ///
   /// Handles circular references where converting one of the elements
   /// to a string ends up converting [set] to a string again.