Update documentation of dart:isolate.

Change-Id: If026cebc668603f80168dfe943646c0c0dc451e9
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/178983
Commit-Queue: Lasse R.H. Nielsen <[email protected]>
Reviewed-by: Nate Bosch <[email protected]>

Author: lrhn

sdk/lib/isolate/capability.dart

@@ -4,31 +4,26 @@
 
 part of dart.isolate;
 
-/**
- * An unforgeable object that comes back as equal when passed through other
- * isolates.
- *
- * Sending a capability object to another isolate, and getting it back,
- * will produce an object that is equal to the original.
- * There is no other way to create objects equal to a capability object.
- *
- * Capabilities can be used as access guards: A remote isolate can send
- * a request for an operation, but it is only allowed if the request contains
- * the correct capability object.
- *
- * This allows exposing the same interface to multiple clients,
- * but restricting some operations to only those clients
- * that have also been given the corresponding capability.
- *
- * Capabilities can be used inside a single isolate,
- * but they have no advantage over
- * just using `new Object` to create a unique object,
- * and it offers no real security against other code
- * running in the same isolate.
- */
+/// An unforgeable object that comes back as equal when passed through other
+/// isolates.
+///
+/// Sending a capability object to another isolate, and getting it back,
+/// will produce an object that is equal to the original.
+/// There is no other way to create objects equal to a capability object.
+///
+/// Capabilities can be used as access guards.
+/// An isolate can receive requests for operations from other isolates,
+/// but only allow them if the request contains the correct capability object.
+/// This allows exposing the same interface to multiple clients,
+/// but restricting some operations to only those clients
+/// that have also been given the corresponding capability.
+///
+/// Capabilities can be used inside a single isolate,
+/// but they have no advantage over
+/// just using `Object()` to create a unique object,
+/// and it offers no real security against other code
+/// running in the same isolate.
 class Capability {
-  /**
-   * Create a new unforgeable capability object.
-   */
+  /// Create a new unforgeable capability object.
   external factory Capability();
 }