Update documentation for RandomAccessFile

sdk/lib/io/file.dart

Index: sdk/lib/io/file.dart
diff --git a/sdk/lib/io/file.dart b/sdk/lib/io/file.dart
index 979d6f607e73c7a0a2352c0dcd7a9fb589b96905..2970c93caffde3fd83c3efec5b8bcc9206311958 100644
--- a/sdk/lib/io/file.dart
+++ b/sdk/lib/io/file.dart
@@ -499,6 +499,18 @@ abstract class File extends FileSystemEntity {
  * [RandomAccessFile] provides random access to the data in a
  * file. [RandomAccessFile] objects are obtained by calling the

[Lasse Reichstein Nielsen, 2014/11/06 09:18:39]

New paragraph after "file.".

Use `RandomAccessFile` instead of [RandomAccessFile] for all but the first
reference (and maybe even for that, we are already at the [RandomAccessFile]
declaration, and you should never have a link to where you already are).

[Søren Gjesse, 2014/11/06 12:06:10]

Removed all []'s for RandomAccessFile.

  * [:open:] method on a [File] object.
+ *
+ * A [RandomAccessFile] have both asynchronous and synchronous

[Lasse Reichstein Nielsen, 2014/11/06 09:18:39]

Swap "synchronous" and "asynchronous". (It sounds a little odd to me this way,
I'd prefer the "foo" before the "non-foo" in "both foo and non-foo".)

[Søren Gjesse, 2014/11/06 12:06:10]

We are "preferring" async over sync, so I think it makes sense to hve async
first.

+ * methods. The asynchronous methods all return a `Future`
+ * whereas the synchronous methods will block the current isolate

[Lasse Reichstein Nielsen, 2014/11/06 09:18:39]

... will return the result directly, and block the current isolate until the
result is ready.

[Søren Gjesse, 2014/11/06 12:06:10]

Done.

+ * and return the result directly.
+ *
+ * At most one asynchronous method can be pending on a given [RandomAccessFile]
+ * instance at the time. If an asynchronous method is called when one is
+ * already in progress a [FileSystemException] is thrown.

[Lasse Reichstein Nielsen, 2014/11/06 09:18:39]

Why the restriction? It would be (much!) better to just not have that
restriction, even if it would require keeping multiple file descriptors under
the hood or similar shenanigans.

Is there any way to detect if a RandomAccessFile is currently performing an
async operation? If not, consider adding an "isActive" flag (or similar).

[Søren Gjesse, 2014/11/06 12:06:10]

If we are to allow several outstanding async operations we are to define the
precise semantics, which would probably be serializing this, as otherwise you
will get undefined behavior.

There is no isActive, and I am not sure we should add that. The user should keep
track of completing futures before calling the next method.

+ *
+ * If an asynchronous method is pending it is also not possible to call any
+ * synchronous methods. This will also throw a [FileSystemException].

[Lasse Reichstein Nielsen, 2014/11/06 09:18:39]

Definitely need a way to see if it's safe.

[Søren Gjesse, 2014/11/06 12:06:10]

Again most likely combining async and sync is a programming error. Open one
RandomAccessFile for sync methods and another one for async, and you are good.
We actually thorough about having a sync and a async RandomAccessFile class to
avoid having both sets of methods on the same class. 

  */
 abstract class RandomAccessFile {
   /**