class-level docs for several dart:io classes

class-level docs for several dart:io classes

BUG=
R=sgjesse@google.com

Committed: https://code.google.com/p/dart/source/detail?r=33023

[mem, 2014-02-12 00:04:58]

Hello:
I've added class-level documentation to File, Directory, Process, Platform, and
FileSystemEntity (5 of the top 20 visited classes in dart:io).

I'd appreciate your feedback. I plan to do the top 20 classes in the next few
weeks, so this is likely to set the style and tone for the others. So, if
there's something you don't like or would prefer that I do in a different way,
please let me know.

Thanks.
mem

[Søren Gjesse, 2014-02-12 13:16:35]

Thanks for working on the documentation. I have some comments.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/directory....
File sdk/lib/io/directory.dart (right):

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/directory....
sdk/lib/io/directory.dart:7: /**
We should have a section on the fact that Directory is both used as an instance
to access the file system and has a number of static methods 'systemTemp' and
'current' (which are not related to a specific directory.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/directory....
sdk/lib/io/directory.dart:10: * A [Directory] has a [path] (the pathname to the
directory) and a [parent]
We should merge this with the first line, and be precise about the fact that a
Directory instance is just an object holding a path on which operations can be
performed.

We should also mention that the path can be either relative or absolute.

The [parent] property is not directly part of the Directory.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/directory....
sdk/lib/io/directory.dart:46: * The list method returns a Stream that serves
FileSystemEntity
serves -> provides

(serves is OK, but I think provides is a bit better)

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/directory....
sdk/lib/io/directory.dart:65: * To avoid unintentional blocking of the program,
Maybe we should rephrase this somehow, e.g.

Whenever an I/O operation is performed the running program could block for some
period of time waiting for the operation to complete. To avoid this all
operations involving I/O has a asynchronous variant which returns a future. This
future completes when the I/O operation has finished. While the I/O operation is
in progress the Dart program is not blocked, but can perform other operations.

... maybe that is a bit long?

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/file.dart
File sdk/lib/io/file.dart (right):

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/file.dart#...
sdk/lib/io/file.dart:38: * A [File] has a [path] (the pathname to the file) and
a [parent] (the
Like for Directory we should be precise about the fact that a File instance is
just an object holding a path on which operations can be performed.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/file.dart#...
sdk/lib/io/file.dart:80: * Open the file with [openRead], which returns a stream
that reads the file as
stream that ... ->

stream that provides the data in the file as chunks of bytes.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/platform.dart
File sdk/lib/io/platform.dart (right):

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/platform.d...
sdk/lib/io/platform.dart:15: * ## Get the URI to the current program
program -> Dart script

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/platform.d...
sdk/lib/io/platform.dart:17: * Use the [script] getter to get the URI to the
currently running program.
ditto.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/platform.d...
sdk/lib/io/platform.dart:46: * getters: [isMacOS], [isLinux], and so on.
so on -> isWindows (there are only these three.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.dart
File sdk/lib/io/process.dart (right):

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:92: * In contrast, the start method allows your code to
interact with the process.
the process -> the running process

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:98: * The code gets the output from the standard output
stream by way of a
Instead of the sentence "The code gest ..." something like this:

Run completes with a [ProcessResult] object when the process terminates. This
provides access to the output and exit code from the process.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:115: * The start method returns a [Future], which
returns a Process object.
which returns -> for

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:116: * Within the [Future]'s callback function, your
code can interact with the
Within the [Future]'s callback function -> When the future completes the process
is started and

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:128: *       Process.start('cat', []).then((Process
proc) {
Why not spell it out: proc -> process

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:143: * `exitCode` returns the code via a [Future]
object.
`exitCode` returns the code via a [Future] object. ->

If process.start is used the exitCode is available through a future on the
[Process] object. If Process.run is used the exitCode is available through a
getter on the ProcessResult instance.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:156: * ## Standard streams
Standard streams -> Standard IO streams

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:158: * As seen in a previous code sample, you can use
the getters [stderr],
the getters -> the top-level getters

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:160: * and standard output streams, respectively.
I don't see this in a previous example, maybe add

import 'dart:io';

main() {
  stdout.writeln('Hello, stdout');
  stderr.writeln('Hello, stderr');
}

[mem, 2014-02-12 19:17:07]

Incorporated your changes.

Thanks.
mem

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/directory....
File sdk/lib/io/directory.dart (right):

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/directory....
sdk/lib/io/directory.dart:7: /**
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> We should have a section on the fact that Directory is both used as an
instance
> to access the file system and has a number of static methods 'systemTemp' and
> 'current' (which are not related to a specific directory.

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/directory....
sdk/lib/io/directory.dart:10: * A [Directory] has a [path] (the pathname to the
directory) and a [parent]
The convention is to have a single one-liner that starts with a noun to start.
Then move to a full directory.

Made adjustments tho to accommodate your comments.

Otherwise, done.

On 2014/02/12 13:16:35, Søren Gjesse wrote:
> We should merge this with the first line, and be precise about the fact that a
> Directory instance is just an object holding a path on which operations can be
> performed.
> 
> We should also mention that the path can be either relative or absolute.
> 
> The [parent] property is not directly part of the Directory.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/directory....
sdk/lib/io/directory.dart:46: * The list method returns a Stream that serves
FileSystemEntity
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> serves -> provides
> 
> (serves is OK, but I think provides is a bit better)

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/directory....
sdk/lib/io/directory.dart:65: * To avoid unintentional blocking of the program,
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> Maybe we should rephrase this somehow, e.g.
> 
> Whenever an I/O operation is performed the running program could block for
some
> period of time waiting for the operation to complete. To avoid this all
> operations involving I/O has a asynchronous variant which returns a future.
This
> future completes when the I/O operation has finished. While the I/O operation
is
> in progress the Dart program is not blocked, but can perform other operations.
> 
> ... maybe that is a bit long?

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/file.dart
File sdk/lib/io/file.dart (right):

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/file.dart#...
sdk/lib/io/file.dart:38: * A [File] has a [path] (the pathname to the file) and
a [parent] (the
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> Like for Directory we should be precise about the fact that a File instance is
> just an object holding a path on which operations can be performed.

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/file.dart#...
sdk/lib/io/file.dart:80: * Open the file with [openRead], which returns a stream
that reads the file as
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> stream that ... ->
> 
> stream that provides the data in the file as chunks of bytes.

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/platform.dart
File sdk/lib/io/platform.dart (right):

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/platform.d...
sdk/lib/io/platform.dart:15: * ## Get the URI to the current program
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> program -> Dart script

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/platform.d...
sdk/lib/io/platform.dart:17: * Use the [script] getter to get the URI to the
currently running program.
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> ditto.

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/platform.d...
sdk/lib/io/platform.dart:46: * getters: [isMacOS], [isLinux], and so on.
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> so on -> isWindows (there are only these three.

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.dart
File sdk/lib/io/process.dart (right):

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:92: * In contrast, the start method allows your code to
interact with the process.
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> the process -> the running process

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:98: * The code gets the output from the standard output
stream by way of a
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> Instead of the sentence "The code gest ..." something like this:
> 
> Run completes with a [ProcessResult] object when the process terminates. This
> provides access to the output and exit code from the process.

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:115: * The start method returns a [Future], which
returns a Process object.
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> which returns -> for

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:116: * Within the [Future]'s callback function, your
code can interact with the
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> Within the [Future]'s callback function -> When the future completes the
process
> is started and

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:128: *       Process.start('cat', []).then((Process
proc) {
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> Why not spell it out: proc -> process

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:143: * `exitCode` returns the code via a [Future]
object.
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> `exitCode` returns the code via a [Future] object. ->
> 
> If process.start is used the exitCode is available through a future on the
> [Process] object. If Process.run is used the exitCode is available through a
> getter on the ProcessResult instance.

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:156: * ## Standard streams
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> Standard streams -> Standard IO streams

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:158: * As seen in a previous code sample, you can use
the getters [stderr],
On 2014/02/12 13:16:35, Søren Gjesse wrote:
> the getters -> the top-level getters

Done.

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:160: * and standard output streams, respectively.
On 2014/02/12 13:16:35, Søren Gjesse wrote:

I was referring to the example above that starts up the `cat` process. I was
also referring to the getters for the Process instance not for the top-level
ones. Maybe I misunderstood the difference. Are they the same thing?

mem


> I don't see this in a previous example, maybe add
> 
> import 'dart:io';
> 
> main() {
>   stdout.writeln('Hello, stdout');
>   stderr.writeln('Hello, stderr');
> }

Done.

[Søren Gjesse, 2014-02-13 16:03:55]

lgtm

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.dart
File sdk/lib/io/process.dart (right):

https://chromiumcodereview.appspot.com/159713011/diff/1/sdk/lib/io/process.da...
sdk/lib/io/process.dart:160: * and standard output streams, respectively.
On 2014/02/12 19:17:07, mem wrote:
> On 2014/02/12 13:16:35, Søren Gjesse wrote:
> 
> I was referring to the example above that starts up the `cat` process. I was
> also referring to the getters for the Process instance not for the top-level
> ones. Maybe I misunderstood the difference. Are they the same thing?
> 
> mem
> 
> 
> > I don't see this in a previous example, maybe add
> > 
> > import 'dart:io';
> > 
> > main() {
> >   stdout.writeln('Hello, stdout');
> >   stderr.writeln('Hello, stderr');
> > }
> 
> Done.

It was just that there was the exit code example in between.

Also they are not the same thing, and I think the change is fine.

[mem, 2014-02-24 21:24:14]

Back from ski trip...sorry it took a while for this edit.

PTAL

mem

[Søren Gjesse, 2014-02-25 13:15:14]

lgtm

[mem, 2014-02-25 17:25:55]

Committed patchset #5 manually as r33023 (presubmit successful).