Update documentation for RandomAccessFile

sdk/lib/io/file.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * The modes in which a File can be opened.
  */
 class FileMode {
@@ skipping 479 matching lines @@
 
   /**
    * Get the path of the file.
    */
   String get path;
 }
 
 
 /**
  * [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 {
   /**
    * Closes the file. Returns a [:Future<RandomAccessFile>:] that
    * completes with this RandomAccessFile when it has been closed.
    */
   Future<RandomAccessFile> close();
 
   /**
    * Synchronously closes the file.
@@ skipping 228 matching lines @@
       sb.write(": $osError");
       if (path != null) {
         sb.write(", path = '$path'");
       }
     } else if (path != null) {
       sb.write(": $path");
     }
     return sb.toString();
   }
 }