Adjust DisposableCollection description

Improved description based on Martin's feedback.

packages/core/src/common/disposable.ts

@@ -48,28 +48,33 @@ Object.defineProperty(Disposable, 'NULL', {
 });
 
 /**
- * Utility for tracking a collection of Disposable objects, specifically for
- * the sake of finding out when all items in the collection have been disposed.
+ * Utility for tracking a collection of Disposable objects.
  *
+ * This utility provides a number of benefits over just using an array of
+ * Disposables:
+ *
+ * - the collection is auto-pruned when an element it contains is disposed by
+ * any code that has a reference to it
+ * - you can register to be notified when all elements in the collection have
+ * been disposed*
+ * - you can conveniently dispose all elements by calling dipose()
+ * on the collection
+ *
+ * Unlike an array, however, this utility does not give you direct access to
+ * its elements.
+ *
+ * Being notified when all elements are disposed is simple:
  * ```
  * const dc = new DisposableCollection(myDisposables);
  * dc.onDispose(() => {
  *    console.log('All elements in the collection have been disposed');
  * });
  * ```
  *
- * You can add any number of Disposables to the collection at any time. You
- * cannot query the contents of the collection. An element is automatically
- * pruned from the collection when it is disposed.
- *
- * The collection will notify only once. It will continue to function
- * in so far as accepting new Disposables and pruning them when they
- * are disposed, but such activity will never result in another
- * notification.
- *
- * Calling dispose() on the collection disposes all its elements. A notification
- * is sent (if no notification was previously sent).
- */
+ * [*] The collection will notify only once. It will continue to function in so
+ * far as accepting new Disposables and pruning them when they are disposed, but
+ * such activity will never result in another notification.
+  */
 export class DisposableCollection implements Disposable {
 
     protected readonly disposables: Disposable[] = [];